Vercel 배포 및 트러블슈팅 마스터 가이드: 빌드 에러, 도메인, 성능 최적화

많은 프론트엔드 프로젝트들이 로컬 호스트 환경에서는 정상 작동하지만, 클라우드 호스팅 서비스인 Vercel로 최종 운영 배포 시도 시 환경 변수 누락, 빌드 에러, 서버리스 실행 한계 초과 등으로 인해 실패하곤 합니다.

본 가이드에서는 Astro 및 모던 프론트엔드 프로젝트의 Vercel 정적/서버 배포 모델 설계부터, 현업 배포 장애 사례(빌드 OOM, 504 Gateway Timeout) 트러블슈팅 해법, 도메인 리다이렉트와 무중단 롤백 파이프라인까지의 전 과정을 분석합니다.

1. 정적 배포(Static) vs 서버 배포(Adapter)

Astro 프로젝트를 Vercel에 연동하기 전, 프로젝트의 렌더링 성격을 먼저 규정해야 합니다.

정적 배포 (Static / SSG): 별도의 서버리스 어댑터 설정 없이 Vercel의 Zero-Configuration 배포 흐름으로 즉시 배포할 수 있으며, 연산 비용이 들지 않고 전 세계 CDN 엣지에 정적 파일이 캐싱됩니다.
서버 배포 (SSR / Hybrid): 이미지 동적 최적화, 미들웨어 처리, API 라우트 연동 등이 요구될 때는 Astro 설정에 Vercel 어댑터를 설치해 주어야 합니다.
```
npx astro add vercel
```
이 명령어는 astro.config.mjs 파일에 @astrojs/vercel 통합 플러그인을 주입하여 빌드 산출물을 Vercel의 Serverless Functions 규격으로 매핑해 줍니다.

2. Vercel 환경별 환경 변수 동기화

Vercel은 로컬 개발 환경(Local), 코드 리뷰 환경(Preview), 실제 사용자 배포 환경(Production)의 세 가지 환경을 분리하여 제공합니다.

환경 변수 누락 주의보: PUBLIC_ 접두사가 필요한 클라이언트 측 변수(예: Google AdSense ID 등)가 Production 환경 세트에만 누락되어 배포 후 정상 노출되지 않는 사고가 흔히 일어납니다.
로컬 개발 동기화 명령: Vercel에 업로드된 최신 환경 변수를 로컬의 개발 환경으로 풀(pull)링하려면 아래의 CLI 명령어를 상시 사용하십시오.
```
vercel link
vercel env pull .env.development.local
```

3. 실전 Vercel 배포 장애 트러블슈팅

💡 빌드 메모리 초과 (OOM - Out of Memory)

대용량 블로그 글의 이미지 처리 또는 복잡한 TypeScript 타입 컴파일 시 빌드 서버의 메모리가 부족해지며 빌드가 끊기는 현상입니다.

원인: Node.js의 기본 가비지 컬렉터 힙 메모리 할당 제한으로 인해 발생합니다.
해결 방안: Vercel 프로젝트 환경 변수에 Node 옵션(NODE_OPTIONS)을 추가하여 할당 메모리를 강제로 늘려줍니다.
```
NODE_OPTIONS = --max-old-space-size=4096
```

💡 504 Gateway Timeout (서버리스 타임아웃)

배포 완료 후 API 요청 시 10초 또는 15초가 지나면 504 에러가 반환되는 장애입니다.

원인: Vercel의 기본 요금제(Hobby)는 Serverless Function의 최대 실행 시간이 10초로 강제 제한되어 있어, 타사 API의 지연이나 무거운 루프 연산이 이 시간을 초과하면 Vercel 게이트웨이가 커넥션을 강제 드롭합니다.
해결 방안: Pro 요금제로 전환 후 vercel.json 설정에 최대 타임아웃 설정을 수동으로 확장하거나, 비즈니스 로직 내의 무거운 처리를 백그라운드 큐(예: Upstash 등)로 위임하고 즉시 202 Accepted 응답을 반환하도록 개선합니다.

4. 커스텀 도메인(Custom Domain) 및 롤백

Apex 도메인과 www 리다이렉션

도메인 추가 시 주 소스(Apex 도메인, 예: myblog.com)와 보조 주소(www.myblog.com)를 동시에 등록하고, Vercel 콘솔 내에서 보조 주소를 주 도메인으로의 301 영구 리다이렉트(Redirect)로 설정해야 이중 인덱싱에 따른 SEO 불이익을 예방할 수 있습니다.

프리뷰 프로모션 (Promotion) 및 롤백 (Rollback)

Promotion: 프리뷰(Preview) 배포 빌드 결과물이 안전하게 검증되면, 해당 빌드를 다시 빌드하지 않고 그대로 프로덕션으로 즉각 승격(vercel promote)시켜 신속 배포합니다.
Rollback: 치명적인 결함이 운영 환경 배포 직후 발견될 경우, Git 리버트를 기다리지 않고 Vercel 배포 대시보드 또는 CLI에서 이전 성공 배포 내역의 Rollback 버튼을 눌러 10초 이내에 정상 이전 상태로 즉각 복구합니다.
```
vercel rollback <deployment-id>
```

FAQ

Q. 배포 완료 후 라이브 검증을 위해 반드시 테스트해야 할 리스트는 무엇인가요?

배포가 정상적으로 완료되었더라도 아래 curl 테스트를 실행해 보아야 합니다.

# 1. 200 OK 응답 및 HTTPS 보안 적용 유무 확인
curl -I https://www.myblog.com/

# 2. 로봇 색인 차단 확인 및 사이트맵 XML 스키마 유무 점검
curl https://www.myblog.com/robots.txt
curl https://www.myblog.com/sitemap-index.xml

특히 다국어 페이지가 결합된 사이트의 경우 캐노니컬(rel="canonical") 태그의 도메인 호스트 정보가 Vercel 임시 배포 주소(vercel.app)가 아닌 고유 커스텀 도메인으로 매핑되었는지 브라우저 개발자 도구의 Elements 창에서 반드시 직접 검사해야 합니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.