Vercel 배포 가이드 — 도메인 연결부터 환경 변수, 프리뷰 배포까지

Vercel은 Next.js를 만든 회사가 운영하는 호스팅 플랫폼이다. 당연히 Next.js와의 궁합이 좋고, React, Vue, Svelte 같은 프레임워크도 지원한다. git push 한 번이면 빌드부터 배포까지 자동으로 처리해주는 게 핵심.

AWS에 직접 배포하려면 EC2 세팅, Nginx 설정, SSL 인증서, CI/CD 파이프라인... 할 게 많다. Vercel은 이 과정을 전부 추상화해서, 코드에만 집중할 수 있게 해준다.

시작하기

Git 리포지토리 연결

vercel.com에 가입 (GitHub 계정으로 로그인하면 편하다)
"New Project" 클릭
GitHub 리포지토리 선택
프레임워크 자동 감지 → "Deploy" 클릭

이게 끝이다. Next.js 프로젝트라면 빌드 명령어(npm run build)와 출력 디렉토리까지 알아서 잡아준다.

배포가 완료되면 프로젝트명.vercel.app 형태의 URL이 할당된다. HTTPS도 자동. 이 상태로도 서비스를 운영할 수 있지만, 보통은 커스텀 도메인을 연결한다.

CLI로 배포하기

웹 대시보드 대신 터미널에서 배포할 수도 있다.

npm i -g vercel
vercel login
vercel         # 프로젝트 루트에서 실행

vercel 명령어를 치면 프로젝트 설정을 물어보고 바로 배포한다. vercel --prod를 붙이면 프로덕션 배포. CI/CD 없이 빠르게 확인하고 싶을 때 유용하다.

커스텀 도메인 연결

DNS 설정

Vercel 대시보드에서 Settings → Domains → 도메인 입력. 그러면 DNS에 추가해야 할 레코드를 알려준다.

보통 두 가지 방식:

A 레코드 — 루트 도메인(example.com)을 연결할 때.

A    @    76.76.21.21

CNAME 레코드 — 서브도메인(www.example.com)을 연결할 때.

CNAME    www    cname.vercel-dns.com

Vercel에서 도메인을 직접 구매했다면 DNS 설정이 자동이다. 외부에서 산 도메인이면 해당 도메인 등록 업체의 DNS 관리 페이지에서 레코드를 추가해야 한다.

SSL 인증서

커스텀 도메인을 연결하면 Let's Encrypt SSL 인증서가 자동으로 발급된다. 갱신도 자동. HTTP → HTTPS 리다이렉트도 기본 설정이다. 인증서 관리를 직접 할 필요가 전혀 없다.

www 리다이렉트

www.example.com과 example.com 둘 다 등록하면 Vercel이 하나로 리다이렉트해준다. SEO 관점에서 하나의 정규 URL을 유지하는 게 좋다. 둘 중 어느 쪽을 메인으로 할지는 대시보드에서 설정.

환경 변수

API 키, 데이터베이스 URL 같은 민감한 값은 코드에 넣으면 안 된다. Vercel의 환경 변수 설정에서 관리한다.

Settings → Environment Variables에서 키-값을 추가하면 빌드 시와 런타임에 process.env.변수명으로 접근할 수 있다.

환경별로 다른 값을 설정할 수 있다는 게 중요하다:

Production — main 브랜치에서 배포될 때 사용
Preview — PR이나 다른 브랜치에서 배포될 때 사용
Development — vercel dev로 로컬에서 돌릴 때 사용

프로덕션 DB와 개발 DB를 다르게 설정하거나, 스테이징 환경에서만 디버그 모드를 켜는 식으로 활용할 수 있다.

# .env.local (로컬 개발용 — git에 커밋하지 않음)
DATABASE_URL=postgresql://localhost:5432/mydb_dev
API_KEY=dev_key_123

# Vercel 대시보드에서 Production 환경으로 설정
# DATABASE_URL=postgresql://prod-server:5432/mydb_prod
# API_KEY=prod_key_456

주의할 점 — Next.js에서 클라이언트 사이드에서 환경 변수를 쓰려면 NEXT_PUBLIC_ 접두사가 필요하다. 이 접두사가 없는 환경 변수는 서버에서만 접근 가능. API 키 같은 민감한 값에 NEXT_PUBLIC_을 붙이는 실수를 하면 클라이언트에 노출되니까 조심해야 한다.

프리뷰 배포

Vercel의 가장 편한 기능 중 하나. PR을 올리면 해당 브랜치의 코드가 자동으로 배포되고, 고유한 URL이 생긴다. PR 페이지에 댓글로 프리뷰 URL이 달린다.

코드 리뷰할 때 리뷰어가 로컬에서 직접 빌드하지 않아도 배포된 버전을 바로 확인할 수 있다. 디자이너나 PM한테 "이 링크에서 확인해주세요" 하면 된다. 커뮤니케이션 비용이 확 줄어든다.

프리뷰 배포에서는 Preview용 환경 변수가 적용되니까, 프로덕션 데이터에 영향을 주지 않고 테스트할 수 있다.

빌드 설정

대부분은 기본 설정으로 충분하지만, 조정이 필요한 경우:

빌드 명령어 변경 — monorepo에서 특정 패키지만 빌드하거나, 커스텀 빌드 스크립트를 쓸 때.

Build Command: cd packages/web && npm run build
Output Directory: packages/web/.next

무시 빌드 단계(Ignored Build Step) — 특정 조건에서 빌드를 건너뛰고 싶을 때. monorepo에서 관련 없는 패키지의 변경으로 불필요한 빌드가 트리거되는 걸 방지.

# 특정 디렉토리에 변경이 없으면 빌드 건너뜀
git diff HEAD^ HEAD --quiet -- packages/web/

Node.js 버전 지정 — package.json의 engines 필드나 대시보드에서 설정. 로컬과 동일한 버전을 쓰는 게 안전하다.

Vercel Functions (서버리스)

Next.js의 API Routes(app/api/)나 Server Actions는 Vercel에서 자동으로 서버리스 함수로 배포된다. 별도 설정 없이 /api/hello에 요청을 보내면 서버리스 함수가 실행된다.

기본 타임아웃은 Hobby 플랜 기준 10초, Pro 플랜 기준 60초. 오래 걸리는 작업이 있다면 이 제한을 인지하고 있어야 한다.

Edge Functions도 지원한다. 사용자에게 가까운 엣지 서버에서 실행되니까 응답 속도가 빠르다. 다만 Node.js API의 일부만 사용 가능해서, fs 같은 모듈은 쓸 수 없다.

요금

Hobby (무료) — 개인 프로젝트용. 빌드 시간 월 100시간, 서버리스 함수 실행 월 100GB-hours, 대역폭 월 100GB. 개인 블로그나 포트폴리오 사이트에는 충분하다.

Pro ($20/월) — 팀 단위 사용. 빌드 시간, 대역폭, 함수 실행 제한이 훨씬 넉넉하고, 팀 멤버 관리, 비밀번호 보호, 분석 기능이 추가된다.

트래픽이 갑자기 폭증하면 과금이 될 수 있다. Vercel 대시보드에서 지출 한도(Spend Limit)를 설정해두면 예상치 못한 과금을 방지할 수 있다. 이걸 설정 안 하고 있다가 바이럴 타면 요금 폭탄 맞을 수 있으니까 꼭 설정해두자.

Vercel 말고 다른 선택지

Vercel이 모든 상황에 정답은 아니다.

Cloudflare Pages — 무료 플랜이 Vercel보다 관대하다. 빌드 횟수 월 500회, 대역폭 무제한. Next.js 지원이 점점 좋아지고 있지만 아직 Vercel만큼 완벽하진 않다.

Netlify — Vercel과 비슷한 포지션. Next.js보다는 정적 사이트나 Astro, Gatsby에 강하다.

Railway/Render — 풀스택 앱(DB + 백엔드 + 프론트)을 한곳에서 관리하고 싶을 때. Vercel은 프론트엔드 중심이라 DB나 장시간 실행 서버가 필요하면 다른 서비스를 조합해야 한다.

Next.js를 쓴다면 Vercel이 가장 편한 건 맞다. 프레임워크 제작사가 호스팅도 하니까 최적화가 잘 되어 있다. 무료 플랜으로 시작해서 트래픽이 늘면 그때 플랜을 올리거나 다른 옵션을 검토하면 된다.