환경 변수 범위를 설명하기 위한 가상 배포입니다. Vercel 화면에는 Ready가 떴지만 운영 로그인은 500을 반환합니다. Preview는 실제 공개 전 별도 주소에서 확인하는 배포이고, Production은 사용자가 접속하는 운영 배포입니다. `AUTH_CALLBACK_URL`이 Preview에만 있고 Production에는 없었다고 가정해 봅시다. Ready는 빌드 파일이 만들어졌다는 표시일 뿐, 운영 로그인까지 정상이라는 보증은 아닙니다.

핵심 배포 완료는 배포 ID, 실제 운영 URL, 핵심 사용자 흐름, 로그, 되돌릴 대상이 한 묶음으로 확인된 상태입니다. Preview와 Production의 환경 변수가 다를 수 있으므로 승격 전에 이름과 범위를 대조하고, 장애 때는 새 빌드를 기다리기보다 이미 운영됐던 정상 배포로 즉시 롤백합니다.

배포 세션도 처음에는 읽기 전용 계획입니다

배포 ID와 주소는 예시 형식이며 실제 값을 넣습니다.

Vercel 배포 전 첫 프롬프트
claude --permission-mode plan

현재 커밋의 Preview 검증과 운영 승격 계획만 작성하세요. 배포 금지.
읽기: CLAUDE.md, 배포 문서, vercel.json, 환경 변수 이름 목록, smoke 테스트
허용: Read, Grep, git diff, vercel의 읽기 명령
금지: 환경 변수 값 출력, promote·rollback, 운영 DB 변경
반환: Preview 흐름 / Production 차이 / 승인 지점 / 롤백 대상 / 검증 명령
중단: 직전 정상 배포나 DB 호환성을 확인할 수 없을 때

배포 담당자가 Preview 결과와 롤백 대상을 확인합니다

배포 담당자는 승인된 Preview URL에서 핵심 흐름과 실제 응답을 확인하고, 코드 변경 차이도 함께 봅니다. 기록에는 배포 ID, 확인한 URL과 미검증 흐름이 남아야 합니다. 운영 승격은 이 기록을 검토한 뒤 별도 단계에서 결정합니다.

비밀 이름이 빠지거나 핵심 흐름이 실패하거나 되돌릴 배포가 불명확하면 중단합니다. 재개 메모에는 배포 ID, 확인 URL, 미검증과 승인 대기 단계를 적습니다.

Ready와 사용 가능한 서비스는 다른 상태입니다

예시 배포는 Ready 상태이고 정적 페이지도 200을 반환하지만, 로그인 콜백은 500이며 런타임 로그에는 콜백 URL 누락이 남습니다. 단순 상태 확인 한 건으로는 동적 경로를 보지 못한 것입니다.

검증 목록은 서비스 가치에 맞춰 짧게 정합니다. 이 예시 서비스에서는 홈 200, 로그인 시작 302, 테스트 계정 로그인 후 대시보드 200, 읽기 전용 API 200의 네 흐름을 확인합니다. 결제나 메일 같은 외부 효과는 Preview에서 실제 발송하지 않고 테스트 공급자와 격리 계정을 씁니다.

환경 변수 값 대신 범위와 이름을 비교합니다

로컬 파일이나 로그에 비밀값을 출력하지 않습니다. Vercel의 Preview와 Production 범위에 필요한 이름이 모두 있는지 대시보드 또는 승인된 CLI로 확인합니다. Preview를 Production으로 승격하면 Production에 연결된 환경 변수로 다시 빌드될 수 있다는 점도 공식 문서에 명시돼 있습니다.

배포 전 남길 수 있는 비밀 없는 점검표
배포 ID: dpl_example
커밋: 8자리 해시 기록
Preview: AUTH_CALLBACK_URL 있음 / DATABASE_URL 있음
Production: AUTH_CALLBACK_URL 있음 / DATABASE_URL 있음
값 출력: 금지
외부 효과: 테스트 계정, 메일 발송 비활성
롤백 대상: 직전 정상 운영 배포 URL

Preview 통과 뒤에도 운영 도메인을 다시 봅니다

Preview URL에서 네 흐름이 모두 통과한 뒤 승인된 배포만 승격합니다. 운영 도메인 연결, Production 변수, 쿠키 도메인과 외부 OAuth 허용 URL은 Preview와 다르므로 같은 검사를 운영 URL에서 반복합니다. 이 예시에서 기대하는 복구 결과는 환경 변수를 추가한 새 배포의 로그인 콜백이 302를 반환하고 대시보드가 200으로 열리는 것입니다.

운영 검증 중 팀이 미리 정한 오류 한계를 넘거나 로그인 흐름이 실패하면 추가 기능 확인을 멈추고 롤백 판단으로 넘어갑니다. DB 마이그레이션이 이미 비호환 상태로 진행됐다면 코드만 롤백할 수 없으므로 배포 전에 구버전 호환 여부를 확인해야 합니다.

즉시 롤백은 재빌드가 아닙니다

Vercel Instant Rollback은 과거에 운영 도메인을 받았던 배포로 도메인을 다시 연결합니다. 새 빌드를 만들지 않으므로 빠르지만, 최근 바꾼 환경 변수를 다시 빌드해 반영하지도 않습니다. 대부분의 Preview처럼 운영에 연결된 적 없는 배포는 즉시 롤백 대상이 아닙니다.

장애 대응과 롤백 해제 명령
vercel rollback https://known-good.example.vercel.app
vercel rollback status --timeout 30s

# 원인이 수정된 배포를 다시 운영으로 승격
vercel promote https://fixed.example.vercel.app

완료 기록은 다음 장애의 출발점입니다

최종 기록에는 운영 URL, 배포 ID, 커밋, 검증한 네 흐름, 확인 시각, 런타임 로그 이상 여부, 정상 롤백 URL을 남깁니다. “배포 성공” 한 줄만 남기면 다음 담당자는 어떤 코드가 실제 트래픽을 받는지 다시 찾아야 합니다.

2026년 7월 29일 Vercel 공식 배포·승격·롤백 문서를 기준으로 확인했습니다. 자동 도메인 할당을 끈 준비 상태의 Production은 빌드 후 트래픽을 받지 않다가 별도 승격할 수 있습니다. 팀의 요금제와 설정에 따라 가능한 절차가 다르면 대시보드의 실제 프로젝트 상태를 우선 확인합니다.

공식 출처