Vercel 배포 전 최종 체크리스트

도입

로컬에서 문제없이 보이던 블로그가 배포에서 실패하는 이유는 대부분 화려한 기능이 아니라 검증 순서 부재다. 특히 파일 기반 콘텐츠 블로그는 환경 변수, 정적 생성, 메타 산출물(sitemap/rss) 중 하나만 어긋나도 전체 배포가 중단될 수 있다.

이 글은 Vercel 배포를 기준으로, 실패를 사전에 차단하는 점검 절차를 정리한다.

문제 정의

배포 장애의 주요 원인은 아래로 수렴한다.

• 빌드 타임 frontmatter 오류 누락
• NEXT_PUBLIC_SITE_URL 누락 또는 오기입
• sitemap.xml, robots.txt, rss.xml 생성 누락
• 내부 링크/404/metadata 경로 불일치

핵심은 "배포 후 확인"이 아니라 "배포 전 차단"이다.

개념 설명

단계별 점검 프레임

필수 환경 변수

• NEXT_PUBLIC_SITE_URL=https://<your-domain>

이 값이 틀리면 canonical/rss/sitemap URL이 연쇄적으로 오염된다.

코드 예시

예시 1: 배포 전 로컬 검증 명령

npm run lint
npm run build

예시 2: CI에서 기본 검증 자동화

name: pre-deploy-check
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm run build

필수 검증은 "사람"이 아니라 파이프라인이 반복해야 안정성이 올라간다.

아키텍처 설명

이 흐름의 목적은 배포 성공률 자체보다 "실패 원인 위치"를 빠르게 좁히는 것이다.

정리

배포 체크리스트의 본질은 항목 수가 아니라 순서와 자동화다. 아래 5가지는 항상 고정해두는 것이 좋다.

1. npm run lint 통과
2. npm run build 통과
3. NEXT_PUBLIC_SITE_URL 검증
4. sitemap.xml, robots.txt, rss.xml 응답 확인
5. 핵심 라우트(/, /posts, /posts/[slug]) 스모크 테스트

블로그 MVP에서는 기능 추가보다 배포 재현성이 더 큰 경쟁력이다. 검증을 코드화하면 운영 리스크가 눈에 띄게 줄어든다.

함께 읽기

• Next.js App Router 블로그 MVP 설계
• MDX 콘텐츠 파이프라인: frontmatter부터 렌더링까지
• Vercel Analytics 첫 적용: 무엇을 먼저 봐야 할까