Vercel 배포 과정

Git 저장소를 Vercel에 연결해 Preview와 운영 배포를 자동화하고 환경 변수·로그·성능을 배포 후 확인합니다.

배포(Deployment)는 개발된 애플리케이션을 사용자가 접근할 수 있는 서버 환경에 올려 서비스하는 과정입니다.

Vercel은 Next.js 기능과 긴밀히 통합된 배포 플랫폼이며, 이 절에서는 배포 흐름과 운영 기준을 함께 봅니다.

이 절에서는 Vercel을 기준으로 GitHub 연동 자동 배포, 환경 변수 관리, 배포 후 모니터링, 성능 확인 절차를 다룹니다.

Vercel이 Next.js와 잘 맞는 이유

Vercel은 Next.js 개발사에서 운영하는 플랫폼이므로, App Router, 서버리스 함수, 이미지 최적화, 프리뷰 배포 같은 기능을 배포 과정에서 바로 연결할 수 있습니다.

주요 확인 항목은 다음과 같습니다.

기본 설정 배포: 대부분의 Next.js 프로젝트는 Vercel이 프레임워크를 감지하고 빌드 및 배포 단계를 제안합니다.
최적화 기능 연동: 이미지·폰트 최적화와 컴파일 기능을 배포 과정에 연결합니다. 실제 빌드 시간은 프로젝트 크기, 캐시, 데이터 조회 작업에 따라 달라집니다.
글로벌 CDN (Content Delivery Network): 빌드 시 미리 렌더한 페이지와 정적 자산은 CDN에서 제공되고, ISR 응답도 라우트의 캐시 설정에 따라 여러 지역에 배포됩니다.
정적 산출물과 함수의 분리: 정적으로 렌더할 수 있는 서버 컴포넌트 페이지는 빌드 산출물로 제공됩니다. 요청 시 동적 렌더링이 필요한 페이지, Route Handler와 서버 액션은 Vercel Functions의 실행 경계를 만들며, Functions는 Fluid compute를 통해 요청량과 I/O 대기 상황에 맞게 확장됩니다.
개발자 경험(DX) 최적화: GitHub/GitLab/Bitbucket 연동을 통한 자동 배포, 즉석 프리뷰(Instant Previews), 환경 변수 관리 UI 등 개발 생산성을 높이는 다양한 도구와 워크플로우를 제공합니다.
자동 스케일링: Vercel Functions는 요청량에 맞춰 인스턴스를 늘리거나 사용하지 않을 때 0까지 줄이므로 애플리케이션 서버를 직접 증설하지 않아도 됩니다.

Git 리포지토리를 연결하고 빌드 설정과 환경 변수를 확인한 뒤 배포합니다.

Vercel 회원가입 및 프로젝트 임포트

Vercel 계정 생성/로그인: vercel.com에 접속하여 GitHub, GitLab, Bitbucket 계정을 통해 회원가입하거나 로그인합니다.

Git 계정으로 로그인하는 것이 가장 편리하며, 이후 자동 배포 설정에 유리합니다.

새 프로젝트 추가: 로그인 후 대시보드에서 Add New... 버튼 또는 Import Git Repository 버튼을 클릭합니다.

Git 리포지토리 선택: Vercel이 연동된 Git 호스팅 서비스(GitHub, GitLab, Bitbucket)에서 배포할 Next.js 프로젝트의 리포지토리를 선택합니다.

만약 리포지토리가 보이지 않는다면, Vercel 앱에 해당 리포지토리의 접근 권한이 있는지 확인해야 합니다.

프로젝트 설정 확인: Vercel은 선택한 리포지토리를 분석하여 자동으로 Next.js 프로젝트임을 인식하고 기본 설정을 제안합니다.

Root Directory: Next.js 프로젝트가 리포지토리의 루트에 있는지, 아니면 서브디렉터리에 있는지 확인하고 올바르게 지정합니다 (모노레포의 경우 특히 중요).
Framework Preset: Next.js로 자동 설정됩니다.
Build Command: next build (기본값)
Output Directory: .next (기본값)
Install Command: yarn install 또는 npm install (기본값)

대부분의 Next.js 프로젝트는 이 기본 설정으로 충분합니다.

특별한 빌드 스크립트나 출력 경로를 사용하지 않는 한 변경할 필요가 없습니다.

배포 시작: 첫 빌드에 필요한 환경 변수까지 설정한 후 Deploy 버튼을 클릭합니다.

Vercel은 Git 리포지토리에서 코드를 클론하고, 빌드하고, 배포합니다.

이 과정은 몇 분 정도 소요될 수 있습니다.

배포 완료: 배포가 성공적으로 완료되면, 고유한 Vercel 도메인([your-project-name]-[random-string].vercel.app)으로 애플리케이션에 접근할 수 있습니다.

Vercel 대시보드에서 배포 상태, 빌드 로그, 함수 로그 등을 확인할 수 있습니다.

Git 연동을 통한 자동 배포

Vercel과 Git 리포지토리를 연동하면 지속적 배포(Continuous Deployment)가 자동으로 설정됩니다.

PR에 연결된 Preview URL로 변경 사항을 검토할 수 있습니다. 운영 브랜치는 프로젝트 설정에서 지정하며 main은 한 예입니다.

Next · Vercel deployment changes

Preview·운영 배포·롤백

Git 연동 시 Preview와 Production은 각 환경 값으로 새 빌드를 만듭니다. Preview 승격과 이전 운영 배포로의 Instant Rollback은 빌드·환경 값·도메인 전환이 다릅니다.

미리보기·운영 배포·롤백의 차이
작업	빌드와 환경	전환되는 대상
개발 브랜치 푸시	Preview 환경으로 새 빌드	검토용 배포 URL
운영 브랜치 반영	Production 환경으로 새 빌드	운영 도메인의 새 배포
Preview를 운영으로 승격	Production 값으로 다시 빌드	완료된 운영 배포로 전환
Instant Rollback	기존 배포 재사용 · 재빌드 없음	운영 도메인을 이전 배포에 연결

개발 브랜치 푸시

빌드와 환경: Preview 환경으로 새 빌드
전환되는 대상: 검토용 배포 URL

운영 브랜치 반영

빌드와 환경: Production 환경으로 새 빌드
전환되는 대상: 운영 도메인의 새 배포

Preview를 운영으로 승격

빌드와 환경: Production 값으로 다시 빌드
전환되는 대상: 완료된 운영 배포로 전환

Instant Rollback

빌드와 환경: 기존 배포 재사용 · 재빌드 없음
전환되는 대상: 운영 도메인을 이전 배포에 연결

Preview 승격은 새 Production 빌드입니다. 이미 Production 값으로 만든 staged 배포의 도메인 승격은 재빌드하지 않습니다. 롤백은 DB·외부 변경을 되돌리거나 기존 배포에 새 환경 값을 주입하지 않습니다.

예시 Preview에는 테스트용 API 주소, Production에는 운영용 API 주소를 설정했다고 합시다. 화면이 정상이라는 이유만으로 Preview에서 쓴 주소가 운영 배포에도 알맞다고 판단하면 안 됩니다. Preview를 Production으로 승격하면 새 운영 빌드가 만들어져 Production 설정값을 사용합니다. 반면 이미 Production 대상으로 만든 배포를 운영 도메인에 연결하는 승격은 그 배포를 다시 빌드하지 않습니다.

빌드 로그에서 사용한 커밋과 환경 범위를 먼저 확인하고, 운영 전환 뒤에는 실제 읽기·쓰기 대상이 맞는지 확인합니다. 비밀값 자체를 로그에 출력하는 방법으로 확인하지는 않습니다.

롤백 범위를 판단하기 새 배포가 DB에 새 필드를 추가한 뒤 문제가 생겼습니다. 이전 배포로 Instant Rollback하면 앱 코드, 이미 변경한 DB, 방금 대시보드에 바꾼 환경 변수는 각각 어떻게 될까요?

기존 배포와 외부 상태의 차이

운영 도메인은 이전 배포를 가리키지만 DB의 변경을 되돌리는 작업은 별도입니다. 롤백은 이전 배포를 재빌드하거나 최신 환경 변수로 갱신하지 않으므로, 되돌린 앱이 현재 DB와 여전히 호환되는지도 확인해야 합니다. 환경 변수 수정만으로 이전 배포의 값을 교체할 수 없습니다.

롤백 뒤에는 자동 운영 도메인 할당도 중지됩니다. 수정된 배포를 만들었다는 사실과 운영 도메인이 그 배포로 전환되었다는 사실을 구별하고, Vercel의 승격·롤백 해제 상태까지 확인합니다.

환경 변수 관리

애플리케이션은 종종 API 키, 데이터베이스 연결 문자열 등 민감한 정보나 환경에 따라 달라지는 값을 사용합니다.

이러한 값은 코드에 직접 포함하지 않고 환경 변수(Environment Variables)로 관리해야 합니다.

Vercel은 환경 변수 관리를 위한 편리한 인터페이스를 제공합니다.

Vercel 대시보드에서 환경 변수 설정

Vercel 대시보드에서 해당 프로젝트를 선택합니다.

Settings 탭으로 이동합니다.

좌측 메뉴에서 Environment Variables를 클릭합니다.

Add New 버튼을 클릭하여 새로운 환경 변수를 추가합니다.

Name: 환경 변수의 이름 (예: DATABASE_URL, NEXT_PUBLIC_API_KEY)
Value: 환경 변수의 값
Environments: 이 환경 변수가 적용될 환경을 선택합니다.
- Development: vercel dev에서 사용하거나, vercel env pull로 내려받아 next dev에서 사용하는 로컬 개발 값
- Preview: 운영 브랜치 외의 미리보기 배포 환경
- Production: 실제 운영 환경 (main 등 설정한 운영 브랜치)

Next.js에서 환경 변수 사용

Next.js에서는 환경 변수를 다음과 같이 사용합니다.

서버 사이드 환경 변수 (Server-side Only): .env 파일에 정의하거나 Vercel 대시보드에서 설정합니다. 일반 서버 전용 값은 브라우저 번들에 공개 값으로 인라인되지 않습니다. 서버에서 읽은 값도 로그나 응답에 직접 내보내면 노출됩니다.
```
// Server Component, Route Handler 등 서버 환경에서만 접근 가능
const dbUrl = process.env.DATABASE_URL;
```
클라이언트 사이드 환경 변수 (Publicly Exposed): NEXT_PUBLIC_ 접두사를 붙여 .env 파일에 정의하거나 Vercel 대시보드에서 설정합니다. 이 변수들은 빌드 시 클라이언트 번들에 포함되므로, API 키 등 노출되어도 괜찮은 정보에만 사용해야 합니다.
```
// 클라이언트 컴포넌트에서도 접근 가능
const apiKey = process.env.NEXT_PUBLIC_API_KEY;
```

로컬 개발 환경 (.env.local): 로컬 개발 시에는 프로젝트 루트에 .env.local 파일을 생성하여 환경 변수를 정의합니다.

이 파일은 Git에 커밋하지 않도록 .gitignore에 추가해야 합니다.

# .env.local 예시
DATABASE_URL=mongodb://localhost:27017/my-app-dev
NEXT_PUBLIC_API_KEY=your_dev_public_api_key

일반 next dev는 로컬 .env.local을 읽고, Vercel의 Preview·Production 배포는 대시보드에서 해당 환경에 설정한 값을 사용합니다.

Vercel의 Development 값을 로컬에서 사용하려면 vercel dev로 실행하거나 vercel env pull로 환경 파일을 내려받습니다.

배포 후 관리 및 최적화

Vercel은 배포 후에도 애플리케이션을 효율적으로 관리하고 성능을 최적화할 수 있는 다양한 도구를 제공합니다.

도메인 설정: Vercel 대시보드에서 쉽게 커스텀 도메인(예: yourdomain.com)을 연결할 수 있습니다. Vercel은 SSL 인증서 발급 및 갱신을 자동으로 처리합니다.
Web Analytics: @vercel/analytics를 연결하여 방문자 수, 페이지 뷰, 유입 경로 같은 트래픽 지표를 확인합니다.
Speed Insights: @vercel/speed-insights를 연결하여 Core Web Vitals (LCP, INP, CLS) 같은 실제 사용자 성능 지표를 확인합니다.
로그 (Logs): 서버리스 함수와 빌드 과정에서 발생하는 로그를 실시간으로 확인하여 문제를 진단할 수 있습니다.
함수 캐싱 (Function Caching): 서버리스 함수에 캐싱 전략을 적용하여 응답 시간을 단축하고 비용을 절감할 수 있습니다.
엣지 캐싱 (Edge Caching): Cache-Control 헤더를 사용하여 Vercel의 CDN에서 정적 자산과 서버 응답을 캐싱하여 성능을 향상시킵니다.
A/B 테스팅 (A/B Testing): Proxy와 rewrite를 활용하여 사용자 그룹별 UI를 나누고 성능을 비교할 수 있습니다.

운영 도메인으로 전환하기 전에는 Preview에서 확인한 기능과 Production 환경 값의 차이를 검토하고, 전환 후에는 오류 로그와 사용자 성능 지표를 확인합니다.

Vercel 배포 과정

Vercel이 Next.js와 잘 맞는 이유