Vercel 배포 가이드 — 도메인 연결부터 환경 변수, 프리뷰 배포까지
Vercel에 프로젝트 배포하는 법. Git 연동, 커스텀 도메인, 환경 변수 설정, 프리뷰 배포 활용까지 정리.
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 CLI로 환경 변수 관리
# 환경 변수 목록 확인
vercel env ls
# 환경 변수 추가 (Production + Preview + Development)
vercel env add DATABASE_URL
# 특정 환경에만 추가
vercel env add API_KEY production
# 환경 변수를 .env.local로 가져오기
vercel env pull .env.local
vercel env pull이 특히 유용하다. 새 팀원이 합류하면 리포를 클론하고 vercel env pull만 실행하면 로컬 환경 변수가 세팅된다. .env 파일을 슬랙으로 주고받는 것보다 훨씬 안전하다.
민감도에 따른 분류
환경 변수를 세 가지로 분류해서 관리하면 실수를 줄일 수 있다:
- Public —
NEXT_PUBLIC_SITE_URL같이 클라이언트에 노출돼도 되는 값.NEXT_PUBLIC_접두사 사용 - Secret —
DATABASE_URL,API_KEY같이 서버에서만 접근해야 하는 값. 접두사 없이 사용 - Sensitive — 결제 키, 인증 시크릿 등. Vercel의 "Sensitive" 토글을 켜면 대시보드에서도 값이 마스킹 된다
실수로 NEXT_PUBLIC_을 붙인 API 키가 클라이언트 번들에 포함되면 누구나 브라우저 개발자 도구에서 볼 수 있다. 환경 변수를 추가할 때마다 "이게 클라이언트에 노출돼도 괜찮은 값인가?" 한번 생각하자.
프리뷰 배포 200% 활용
기본적으로 PR마다 프리뷰 URL이 생기는 건 알았는데, 몇 가지 더 할 수 있는 게 있다.
브랜치별 고정 URL
프리뷰 배포는 매번 고유 URL이 생기지만, 브랜치 이름 기반의 고정 URL도 제공된다. feature/redesign 브랜치의 프리뷰는 프로젝트명-git-feature-redesign-유저명.vercel.app 형태다. 이 URL은 해당 브랜치에 새 커밋이 푸시될 때마다 최신 버전으로 업데이트되니까, 디자이너에게 "이 링크로 계속 확인해주세요"라고 한 번만 공유하면 된다.
프리뷰 댓글 활용
Vercel은 PR에 자동으로 프리뷰 URL을 댓글로 달아준다. 여기에 Lighthouse 성능 점수, 빌드 시간, 번들 사이즈 변화량도 포함된다. 코드 리뷰할 때 성능 퇴행이 있는지 바로 확인할 수 있어서 유용하다.
프리뷰 배포 보호
팀 외부에 프리뷰가 공개되면 곤란한 경우 — 아직 출시 전인 기능이라든가 — Vercel Pro 플랜에서는 프리뷰 배포에 비밀번호 보호를 걸 수 있다. Settings → General → Password Protection에서 설정한다.
Edge Functions
Vercel Functions (서버리스)에 더해, Edge Functions도 지원한다. 차이를 정리하면:
서버리스 함수 — 특정 리전(기본 iad1, US East)에서 실행된다. Node.js 전체 API를 쓸 수 있고, 타임아웃이 넉넉하다. DB 쿼리처럼 특정 리전의 자원에 접근해야 할 때 적합하다.
Edge Functions — 사용자에게 가장 가까운 엣지 서버에서 실행된다. 전 세계 수십 개 지점에 배포되니까 응답 속도가 빠르다. 다만 Node.js API의 일부만 사용 가능해서 fs, child_process 같은 모듈은 쓸 수 없다. V8 런타임 기반이라 제약이 있는 대신 콜드 스타트가 거의 없다.
// Edge Function 예시 (app/api/geo/route.ts)
export const runtime = "edge";
export function GET(request: Request) {
const country = request.headers.get("x-vercel-ip-country") || "unknown";
return Response.json({ country });
}
export const runtime = "edge"를 추가하면 해당 라우트가 Edge Function으로 배포된다. 지역 기반 콘텐츠 제공, A/B 테스트, 인증 토큰 검증 같이 가벼우면서 빨라야 하는 작업에 맞다. DB 접근이 필요한 무거운 로직은 서버리스 함수에 두는 게 낫다.
Next.js의 API Routes(app/api/)나 Server Actions는 Vercel에서 자동으로 서버리스 함수로 배포된다. 별도 설정 없이 /api/hello에 요청을 보내면 서버리스 함수가 실행된다.
Fluid Compute가 기본 활성화되면서 서버리스 함수 타임아웃이 확장됐다. 정확한 한도는 플랜에 따라 다르니 공식 문서를 확인하자. 자세한 내용은 Vercel 공식 문서를 참고하자.
요금
Hobby (무료) — 개인 프로젝트용. 넉넉한 빌드 및 대역폭 한도가 포함되어 있다. 개인 블로그나 포트폴리오 사이트에는 충분하다. 최신 한도는 vercel.com/pricing에서 확인하자.
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이 가장 편한 건 맞다. 프레임워크 제작사가 호스팅도 하니까 최적화가 잘 되어 있다. 무료 플랜으로 시작해서 트래픽이 늘면 그때 플랜을 올리거나 다른 옵션을 검토하면 된다.