Vercel 배포 과정

배포(deployment)는 개발한 애플리케이션을 사용자가 접근할 수 있는 서버 환경에 올려 서비스하는 과정입니다. Vercel은 Next.js의 기능과 긴밀하게 통합된 배포 플랫폼입니다.

15장에서는 Vercel 배포, 환경 변수 설정, 커스텀 도메인 연결, 외부 호스팅 배포를 차례로 다루며 Next.js 애플리케이션을 서비스하는 방법을 살펴봅니다. 이 글에서는 Vercel을 기준으로 GitHub 연동 자동 배포, 환경 변수 관리, 배포 뒤의 모니터링과 성능 확인 절차를 다룹니다.

Vercel이 Next.js와 잘 맞는 이유

Vercel은 Next.js를 만든 회사가 운영하는 플랫폼이므로, App Router, 서버리스 함수, 이미지 최적화, 미리보기 배포 같은 기능을 배포 과정에서 바로 연결할 수 있습니다. 대부분의 Next.js 프로젝트는 Vercel이 프레임워크를 감지해 빌드와 배포 단계를 제안하며, 이미지와 폰트 최적화, 컴파일 기능도 배포 과정에 연결됩니다. 실제 빌드 시간은 프로젝트 크기, 캐시, 데이터 조회 작업에 따라 달라집니다.

빌드할 때 미리 렌더링한 페이지와 정적 자산은 글로벌 CDN(Content Delivery Network)에서 제공되고, ISR 응답도 라우트의 캐시 설정에 따라 여러 지역에 배포됩니다. 정적으로 렌더링할 수 있는 서버 컴포넌트 페이지는 빌드 산출물로 제공되고, 요청할 때 동적으로 렌더링해야 하는 페이지와 Route Handler, 서버 액션은 Vercel Functions에서 실행됩니다. Functions는 Fluid compute로 요청량과 I/O 대기 상황에 맞게 늘어나며, 쓰지 않을 때는 0까지 줄어들므로 애플리케이션 서버를 직접 늘릴 필요가 없습니다.

GitHub, GitLab, Bitbucket과 연동한 자동 배포, 즉석 미리보기(Instant Previews), 환경 변수 관리 UI처럼 개발 생산성을 높이는 도구와 작업 흐름도 제공합니다.

Vercel 배포 과정

배포는 Git 저장소를 연결하고, 빌드 설정과 환경 변수를 확인한 뒤 진행합니다. 처음 한 번은 대시보드에서 저장소를 가져와 프로젝트를 만들고, Vercel이 제안한 빌드 설정과 첫 빌드에 필요한 환경 변수를 확인한 뒤 Deploy를 누릅니다. 그다음부터는 저장소에 푸시할 때마다 Vercel이 새 배포를 만들므로, 아래 두 절은 첫 배포의 화면 순서와 그 뒤의 자동 배포가 브랜치에 따라 어떻게 나뉘는지를 차례로 다룹니다.

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

먼저 vercel.com에 접속해 GitHub, GitLab, Bitbucket 계정으로 가입하거나 로그인합니다. Git 계정으로 로그인하는 것이 가장 편하고, 이후 자동 배포를 설정하기에도 좋습니다. 로그인한 뒤 대시보드의 Add New... 메뉴에서 Project를 고르거나 Import Git Repository를 눌러 새 프로젝트를 추가하고, 연동된 Git 호스팅 서비스에서 배포할 Next.js 프로젝트의 저장소를 고릅니다. 저장소가 보이지 않는다면 Vercel 앱에 그 저장소에 대한 접근 권한이 있는지 확인합니다.

Vercel은 고른 저장소를 분석해 Next.js 프로젝트임을 자동으로 알아보고 기본 설정을 제안합니다. Root Directory에는 Next.js 프로젝트가 저장소의 루트에 있는지 하위 디렉터리에 있는지 확인해 올바르게 지정하며, 모노레포에서는 특히 중요합니다. Framework Preset은 Next.js로 자동 설정되고, Build Command는 기본값인 next build, Output Directory는 기본값인 .next, Install Command는 기본값인 npm install이나 yarn install입니다. 특별한 빌드 스크립트나 출력 경로를 쓰지 않는다면 대부분 이 기본 설정으로 충분합니다.

첫 빌드에 필요한 환경 변수까지 설정한 뒤 Deploy 버튼을 누르면, Vercel이 저장소에서 코드를 가져와 빌드하고 배포하며 몇 분 정도 걸릴 수 있습니다. 배포가 끝나면 [your-project-name]-[random-string].vercel.app 같은 고유한 Vercel 도메인으로 애플리케이션에 접근할 수 있고, 대시보드에서 배포 상태, 빌드 로그, 함수 로그 등을 확인할 수 있습니다.

Git 연동을 통한 자동 배포

Vercel과 Git 저장소를 연동하면 지속적 배포(continuous deployment)가 자동으로 설정됩니다. PR에 연결된 Preview URL로 변경 사항을 검토할 수 있으며, 운영 브랜치는 프로젝트 설정에서 지정하고 main은 그 한 예입니다.

위 표는 Git 연동에서 Preview 배포, 운영 배포, 롤백이 각각 무엇을 빌드하고 무엇을 전환하는지 비교합니다. 개발 브랜치에 푸시하면 Preview 환경의 값으로 새 빌드를 만들어 검토용 배포 URL을 주고, 운영 브랜치에 반영하면 Production 환경의 값으로 새 빌드를 만들어 운영 도메인에 새 배포를 연결합니다. Preview 배포를 운영으로 승격하면 Production 값으로 다시 빌드해 완성된 운영 배포로 전환하고, Instant Rollback은 다시 빌드하지 않고 기존 배포를 재사용해 운영 도메인을 이전 배포에 연결합니다.

표의 설명처럼 Preview 승격은 새 Production 빌드이지만, 이미 Production 값으로 만들어 두었던(staged) 배포를 운영 도메인에 승격할 때는 다시 빌드하지 않습니다. 롤백은 DB나 외부의 변경을 되돌리거나 기존 배포에 새 환경 값을 넣지 않습니다.

예를 들어 Preview에는 테스트용 API 주소를, Production에는 운영용 API 주소를 설정했다고 합시다. 화면이 정상이라는 이유만으로 Preview에서 쓴 주소가 운영 배포에도 알맞다고 판단하면 안 됩니다. 빌드 로그에서 쓰인 커밋과 환경 범위를 먼저 확인하고, 운영으로 전환한 뒤에는 실제로 읽고 쓰는 대상이 맞는지 확인합니다. 비밀 값 자체를 로그에 출력하는 방식으로 확인하지는 않습니다.

환경 변수 관리

애플리케이션은 API 키나 데이터베이스 연결 문자열처럼 민감한 정보, 또는 환경에 따라 달라지는 값을 자주 씁니다. 이런 값은 코드에 직접 넣지 않고 환경 변수(environment variables)로 관리해야 하며, Vercel은 환경 변수를 관리하는 편리한 화면을 제공합니다.

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

Vercel 대시보드에서 프로젝트를 고르고 Settings 탭으로 이동한 뒤, 왼쪽 메뉴의 Environment Variables에서 새 환경 변수를 추가합니다. Name에는 DATABASE_URL, NEXT_PUBLIC_API_KEY 같은 이름을, Value에는 값을 넣고, Environments에서 이 값을 적용할 환경을 고릅니다. Development는 vercel dev에서 쓰거나 vercel env pull로 내려받아 next dev에서 쓰는 로컬 개발 값이고, Preview는 운영 브랜치가 아닌 미리보기 배포 환경, Production은 main처럼 설정한 운영 브랜치의 실제 운영 환경입니다.

Next.js에서 환경 변수 사용

Next.js에서 접두사가 없는 일반 환경 변수는 서버 전용입니다. .env 파일에 정의하거나 Vercel 대시보드에서 설정하며, 브라우저 번들에 공개 값으로 들어가지 않습니다. 다만 서버에서 읽은 값도 로그나 응답에 그대로 내보내면 노출됩니다.

// Server Component, Route Handler 등 서버 환경에서만 접근 가능
const dbUrl = process.env.DATABASE_URL;

NEXT_PUBLIC_ 접두사를 붙인 변수는 빌드할 때 클라이언트 번들에 들어가므로, 노출되어도 괜찮은 정보에만 써야 합니다. Next.js는 빌드할 때 코드에 적힌 process.env.NEXT_PUBLIC_API_KEY를 실제 값 문자열로 바꿔 넣습니다. 그래서 빌드한 뒤에 값을 바꿔도 이미 만든 번들에는 반영되지 않고, process.env[name]처럼 이름을 변수로 계산해 읽으면 바꿔 넣을 대상을 찾지 못해 값이 들어가지 않습니다.

// 클라이언트 컴포넌트에서도 접근 가능
const apiKey = process.env.NEXT_PUBLIC_API_KEY;

로컬에서 개발할 때는 프로젝트 루트에 .env.local 파일을 만들어 환경 변수를 정의하며, 이 파일은 Git에 커밋하지 않도록 .gitignore에 넣어야 합니다. 형식은 한 줄에 이름=값 하나이며, #으로 시작하는 줄은 주석입니다. create-next-app으로 만든 프로젝트의 .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은 배포 뒤에도 애플리케이션을 관리하고 성능을 최적화하는 여러 도구를 제공합니다. 대시보드에서 yourdomain.com 같은 커스텀 도메인을 쉽게 연결할 수 있고, SSL 인증서의 발급과 갱신도 자동으로 처리됩니다. @vercel/analytics를 연결하면 방문자 수, 페이지 뷰, 유입 경로 같은 트래픽 지표를, @vercel/speed-insights를 연결하면 LCP, INP, CLS 같은 Core Web Vitals의 실제 사용자 성능 지표를 확인할 수 있습니다. 서버리스 함수와 빌드 과정의 로그도 실시간으로 확인해 문제를 진단할 수 있습니다.

함수의 응답에 캐싱 전략을 적용하면 응답 시간을 줄이고 비용을 아낄 수 있으며, Cache-Control 헤더로 Vercel의 CDN에서 정적 자산과 서버 응답을 캐싱해 성능을 높일 수 있습니다. Proxy와 rewrite를 활용해 사용자 그룹별로 UI를 나누고 성능을 비교하는 A/B 테스트도 할 수 있습니다.

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

정리

• Vercel은 Git 저장소를 연결하면 Next.js를 감지해 빌드 설정을 제안하고, 정적 산출물은 CDN에서, 동적 렌더링과 Route Handler는 Vercel Functions에서 실행합니다.
• 운영 브랜치가 아닌 브랜치의 푸시는 Preview 배포를, 운영 브랜치의 반영은 Production 배포를 만들며, 각 환경은 자신의 환경 변수 값으로 빌드됩니다.
• Instant Rollback은 기존 배포를 다시 빌드하지 않고 운영 도메인에 연결할 뿐, DB 변경이나 바뀐 환경 변수를 되돌리거나 반영하지 않습니다.
• 접두사 없는 환경 변수는 서버 전용이고, NEXT_PUBLIC_ 변수는 빌드할 때 브라우저 번들에 들어갑니다.
• 로컬은 .env.local을, 배포는 대시보드의 환경별 값을 쓰며, Vercel의 Development 값은 vercel env pull로 내려받습니다.

연습 문제

1. 롤백 범위를 판단하기

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

2. 환경 변수를 바꾼 뒤의 운영 배포

Production 환경의 DATABASE_URL을 대시보드에서 새 값으로 바꿨습니다. 이미 실행 중인 운영 배포는 곧바로 새 값을 쓸까요?

3. 모노레포의 Root Directory

저장소의 apps/web 폴더에 Next.js 프로젝트가 있고, 루트에는 다른 패키지들이 있습니다. Root Directory를 기본값인 저장소 루트로 둔 채 배포하면 어떤 문제가 생길 수 있을까요?

Vercel의 배포와 환경 변수 설정은 Vercel의 Next.js 배포 문서와 Next.js 공식 문서의 Deploying 안내에서 확인할 수 있습니다.

다음 글 환경 변수 설정에서는 Next.js가 환경 변수를 읽는 순서와, 서버 전용 값과 공개 값을 나누는 방법을 더 자세히 알아봅니다.