Vercel로 프로젝트 배포하기 | Deploy | Claude Code, 제대로 배우기

Vercel에 GitHub 저장소를 연결해 push 한 번으로 빌드와 배포까지 자동으로 처리합니다

Overview

구현은 끝났지만 누구나 접속할 수 있는 URL은 아직 없습니다.

이 레슨에서는 Vercel에 GitHub 저장소를 연결해, push 한 번이 곧 배포가 되는 환경을 만듭니다.

Vercel 대시보드에서 Add New... > Project를 클릭합니다.

Vercel 대시보드의 Add New Project 버튼

GitHub 저장소 목록에서 프로젝트를 찾아 Import를 클릭합니다.

Vercel GitHub 저장소 Import 화면

다음 화면에서 Deploy 버튼을 클릭하면 Vercel이 Framework(Next.js)를 자동으로 감지하고 빌드를 시작합니다. 별도 설정은 필요 없습니다.

빌드가 완료되면 .vercel.app 도메인의 고유 URL이 생성됩니다.

Vercel 배포 완료 후 생성된 .vercel.app 도메인 화면

이 URL로 접속해 로컬과 동일하게 동작하는지 확인합니다.

한 번 연결되면 그 다음부터는 손댈 일이 없습니다. push가 곧 배포가 됩니다.

이벤트	Vercel 동작
`main` 브랜치에 push	새 빌드 → `.vercel.app` 운영 URL 갱신
PR 생성	Preview URL 자동 생성: 머지 전에 배포 결과를 미리 확인
PR 갱신	같은 Preview URL이 새 커밋으로 갱신

코드 리뷰와 동작 확인을 한 자리에서 끝낼 수 있어, 머지 전 검토 사이클이 짧아집니다.

배포가 실패하면 Vercel 대시보드의 빌드 로그에 원인이 적혀 있습니다. 가장 흔한 케이스 두 가지입니다.

증상	확인할 것
빌드 로그에 TypeScript 또는 ESLint 에러	로컬에서 `bun run build` 실행 → 같은 에러 재현 → 고친 뒤 push
환경 변수 누락 (예: API 키)	Vercel 프로젝트 Settings > Environment Variables 에 추가 후 재배포

로컬 bun run build가 통과하는데 Vercel만 실패하면 환경 변수 문제입니다. 통과하지 않으면 코드 문제입니다.

연결은 한 번만: Vercel에 GitHub 저장소를 한 번 연결하면, 그 다음부터 push가 곧 배포입니다
PR Preview로 머지 전 검토: PR마다 Preview URL이 자동 생성되어, 머지 전에 시각 확인까지 한 자리에서 끝낼 수 있습니다
빌드 실패는 로컬에서 재현: Vercel 빌드 로그를 보고 bun run build로 로컬 재현이 가능하면 코드 문제, 아니면 환경 변수 문제입니다

Q: 커스텀 도메인을 연결할 수 있나요?
- A: 가능합니다. Vercel 프로젝트 Settings > Domains에서 도메인을 추가하고 안내된 DNS 레코드를 설정하면 됩니다.
Q: 배포 횟수에 제한이 있나요?
- A: 무료(Hobby) 플랜도 push마다 자동 배포가 동작합니다. 다만 일일 배포 100회, 빌드 실행 6,000분/월, 데이터 전송 100GB/월 한도가 있어 트래픽이 많은 서비스라면 Pro 플랜으로 올립니다.
Q: 환경 변수를 코드에 어떻게 사용하나요?
- A: process.env.<NAME>으로 접근합니다. 기본값은 서버 전용이라 안전합니다. 클라이언트에서도 사용하려면 변수명에 NEXT_PUBLIC_ 접두사를 붙여 빌드 시 번들에 포함되도록 합니다 (브라우저에서 누구나 볼 수 있으니 API 키·시크릿은 붙이지 않습니다).

배포까지 끝나면 한 사이클이 닫힙니다. 다음 레슨 Compound에서는 한 사이클을 돌며 쌓인 약한 신호를 도구로 승격해 다음 사이클을 더 빠르게 만드는 과정을 다룹니다.