localhost:3000에서 잘 실행된다면 이제 다음 단계는 다른 사람도 접속할 수 있도록 인터넷에 공개하는 것입니다.이번 글에서는 코딩을 처음 접하는 사람도 따라갈 수 있도록 GitHub에 올린 Next.js 프로젝트를 Vercel에 연결해 실제 주소로 배포하는 과정을 처음부터 정리합니다. 배포 전에 무엇을 확인해야 하는지, 환경변수는 어디에 넣는지, 배포가 실패했을 때 어디부터 확인해야 하는지도 함께 살펴보겠습니다.
1. 배포란 무엇이고 왜 필요한가?
개발 중에는 보통 내 컴퓨터에서 프로젝트를 실행합니다. 브라우저 주소창에 http://localhost:3000을 입력해서 화면을 확인했다면 아직 서비스가 내 컴퓨터 안에서만 돌아가고 있는 상태입니다.
배포(Deploy)는 이렇게 만든 웹서비스를 인터넷에서 실행할 수 있는 서버 환경에 올려 다른 사람도 접속할 수 있게 만드는 과정입니다.
↓
GitHub에 코드 저장
↓
Vercel이 프로젝트 빌드
↓
인터넷 주소 생성
↓
다른 사람이 웹사이트 접속
쉽게 말하면 localhost는 내 작업실이고, 배포는 완성한 서비스를 실제 매장에 내놓는 과정이라고 생각하면 됩니다.
코드가 완성되었다고 프로젝트가 끝난 것은 아닙니다. 실제 사용자가 접속하려면 반드시 배포 과정이 필요합니다.
2. Vercel에 올리기 전에 무엇을 확인해야 할까?
AI에게 “이제 배포해줘”라고 바로 요청하기 전에 로컬 환경에서 프로젝트가 정상적으로 빌드되는지 먼저 확인하는 것이 좋습니다.
개발 서버만 되는 것과 배포 가능한 것은 다르다
npm run dev가 정상 실행된다고 해서 실제 배포용 빌드까지 반드시 성공하는 것은 아닙니다. 개발 모드에서는 넘어가던 타입 오류나 빌드 오류가 배포 단계에서 발견될 수 있습니다.
npm run build이 명령어는 실제 서비스에 사용할 수 있는 형태로 프로젝트를 빌드합니다. 오류 없이 완료되면 배포 준비가 한 단계 끝난 것입니다.
| 확인 항목 | 초보자 기준 확인 방법 |
|---|---|
| 로컬 실행 | npm run dev 후 주요 화면 확인 |
| 프로덕션 빌드 | npm run build가 오류 없이 완료되는지 확인 |
| Git 상태 | 최신 변경사항을 Commit 했는지 확인 |
| 환경변수 | .env.local에 필요한 값이 무엇인지 목록 확인 |
| 비밀키 | API Key나 DB 비밀번호가 코드에 직접 들어가 있지 않은지 확인 |
.env.local 파일 자체를 GitHub에 올리는 방식으로 비밀키를 공유하면 안 됩니다. 배포 서비스의 환경변수 설정에 필요한 값만 별도로 등록해야 합니다.3. 프로젝트를 GitHub에 Push하자
Vercel은 GitHub 저장소를 연결해 배포하는 방식을 초보자가 사용하기 좋습니다. 이미 Git을 사용하고 있다면 현재 프로젝트의 변경사항을 먼저 저장한 뒤 GitHub에 올립니다.
git add .
git commit -m "prepare for deployment"
git push origin main각 명령어의 의미는 아래와 같습니다.
| 명령어 | 의미 |
|---|---|
git add . |
현재 변경한 파일을 저장 대상으로 추가 |
git commit |
현재 코드 상태를 하나의 기록으로 저장 |
git push |
내 컴퓨터의 Git 기록을 GitHub 저장소에 업로드 |
“현재 프로젝트를 Vercel에 배포하려고 해. 먼저 Git 상태를 확인하고, 배포 전에 커밋해야 할 변경사항과 주의할 파일이 있는지 알려줘. 비밀키나 .env 파일은 절대 커밋하지 말아줘.”
AI가 Git 명령어를 실행해주더라도 실제로 어떤 파일이 올라가는지는 한 번 확인하는 습관을 들이는 것이 좋습니다.
4. Vercel에서 GitHub 프로젝트를 Import하는 방법
GitHub에 프로젝트가 올라갔다면 Vercel에서 새로운 프로젝트를 만들고 해당 Repository를 연결할 수 있습니다.
↓
새 프로젝트 생성
↓
GitHub Repository 선택
↓
Framework 자동 감지
↓
Deploy 실행
Next.js 프로젝트라면 대부분의 경우 Vercel이 프레임워크와 기본 빌드 설정을 자동으로 감지합니다. 일반적인 프로젝트라면 처음부터 Build Command나 Output Directory를 억지로 수정하기보다 기본값으로 먼저 배포해보는 편이 좋습니다.
배포가 성공하면 아래와 비슷한 주소가 생성됩니다.
https://my-project.vercel.app이제 이 주소는 내 컴퓨터가 아니라 인터넷에 공개된 주소입니다. 휴대폰이나 다른 컴퓨터에서도 접속해 실제로 동작하는지 확인할 수 있습니다.
처음 배포에서는 설정을 많이 바꾸지 않는 것이 좋습니다. Vercel이 Next.js를 정상 감지했다면 기본 설정으로 먼저 성공시키고, 필요한 설정만 하나씩 추가하세요.
5. 환경변수는 Vercel에서 다시 등록해야 한다
Supabase, OpenAI API, 외부 서비스 API 등을 사용하는 프로젝트라면 로컬에서 .env.local 파일을 사용했을 가능성이 높습니다.
하지만 이 파일은 GitHub에 올리지 않는 것이 기본이므로 Vercel 서버는 그 값을 자동으로 알 수 없습니다. 따라서 Vercel 프로젝트 설정에서 환경변수를 다시 등록해야 합니다.
예를 들어 프로젝트가 아래 값을 사용한다고 가정해보겠 습니다.
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
OPENAI_API_KEY=...Vercel의 프로젝트 설정에서 같은 이름으로 Key와 Value를 등록합니다. 등록한 환경변수는 Production, Preview, Development 등 필요한 환경 범위에 맞게 적용할 수 있습니다.
| 종류 | 설명 |
|---|---|
| Production | 실제 사용자에게 공개되는 운영 배포에 사용 |
| Preview | 브랜치나 Pull Request를 미리 확인하는 배포에 사용 |
| Development | 로컬 개발과 연결할 때 사용할 수 있는 개발용 범위 |
Next.js에서
NEXT_PUBLIC_ 접두사가 붙은 환경변수는 브라우저에서 사용하는 코드에 포함될 수 있습니다. 서버에서만 사용해야 하는 비밀키에는 이 접두사를 붙이지 않는 것이 중요합니다.환경변수를 새로 추가하거나 값을 변경한 뒤에는 새 배포가 필요할 수 있습니다. 값만 저장하고 기존 배포 화면을 계속 새로고침했는데 변화가 없다면 재배포 여부를 먼저 확인하세요.
6. 배포가 실패했을 때는 Build Log부터 보자
처음 Vercel 배포를 하면 한 번에 성공할 수도 있지만, Build Failed 같은 메시지를 만나는 경우도 흔합니다. 이때 가장 중요한 것은 무작정 AI에게 “안 돼”라고 말하는 것이 아니라 실패 로그를 그대로 전달하는 것입니다.
자주 확인할 항목
| 문제 | 확인할 내용 |
|---|---|
| Build 오류 | 로컬에서 npm run build도 실패하는지 확인 |
| 환경변수 누락 | Vercel에 필요한 Key가 모두 등록되어 있는지 확인 |
| 패키지 오류 | package.json과 lock 파일이 정상인지 확인 |
| 대소문자 문제 | 파일명과 import 경로의 대소문자가 정확히 일치하는지 확인 |
| 외부 API 오류 | 운영 도메인이 허용 목록에 포함되어야 하는 서비스인지 확인 |
“Vercel 배포 중 아래 Build Log에서 실패했어. 오류가 발생한 첫 번째 원인을 먼저 찾아줘. 추측으로 여러 파일을 한꺼번에 수정하지 말고, 원인 후보와 확인 방법을 설명한 뒤 필요한 최소 변경만 제안해줘.”
오류 메시지 전체를 한꺼번에 고치기보다 가장 먼저 발생한 오류부터 하나씩 해결하는 것이 좋습니다. 뒤에 표시되는 여러 오류가 사실 첫 번째 오류 때문에 연쇄적으로 발생한 것일 수 있기 때문입니다.
7. Preview와 Production 배포는 무엇이 다를까?
GitHub와 Vercel을 연결하면 단순히 한 번 사이트를 올리는 것으로 끝나지 않습니다. 이후 코드를 수정하고 Push할 때마다 새로운 배포를 만들 수 있습니다.
초보자라면 우선 아래 정도로 이해하면 충분합니다.
| 구분 | 역할 | 언제 사용? |
|---|---|---|
| Preview | 수정 중인 버전을 별도 URL로 확인 | 새 기능 테스트, 리뷰 |
| Production | 실제 사용자가 접속하는 운영 버전 | 검증이 끝난 안정적인 버전 |
예를 들어 새로운 로그인 화면을 만드는 브랜치를 GitHub에 Push하면 Preview 주소에서 먼저 확인한 뒤 문제가 없을 때 운영 브랜치에 반영하는 식으로 사용할 수 있습니다.
AI가 큰 기능을 수정했을 때 바로 운영 사이트에 반영하기보다 Preview에서 로그인, 저장, 모바일 화면 등 주요 기능을 먼저 확인하면 사고를 크게 줄일 수 있습니다.
8. 배포 후에는 실제 사용자처럼 다시 테스트하자
Vercel에서 “Deployment Ready”가 표시되었다고 모든 작업이 끝난 것은 아닙니다. 로컬에서는 정상이었지만 운영 환경에서만 문제가 발생하는 기능이 있을 수 있습니다.
최소한 아래 항목은 직접 확인해보는 것이 좋습니다.
| 테스트 항목 | 확인 내용 |
|---|---|
| 메인 화면 | 첫 화면이 정상적으로 열리는가? |
| 페이지 이동 | 주요 링크와 버튼이 모두 동작하는가? |
| 로그인 | 회원가입과 로그인 흐름이 운영 주소에서도 되는가? |
| 데이터 저장 | DB 조회·등록·수정이 정상적인가? |
| 이미지/파일 | Storage 파일이 정상적으로 보이는가? |
| 모바일 | 휴대폰 화면에서도 레이아웃이 깨지지 않는가? |
| 새로고침 | 하위 페이지에서 새로고침해도 오류가 없는가? |
서비스에 Supabase Auth, OAuth, 결제, Webhook 같은 외부 연동이 있다면 운영 도메인을 해당 서비스 설정에 추가해야 하는 경우도 있습니다. 따라서 “로컬에서는 되는데 배포 후 안 된다”면 코드만 보지 말고 외부 서비스의 Redirect URL이나 허용 도메인 설정도 함께 확인해야 합니다.
9. Vercel 배포 흐름 한 번에 정리
이번 편에서 가장 중요한 것은 배포 버튼의 위치를 외우는 것이 아닙니다. 내 컴퓨터의 코드를 인터넷에서 동작하는 서비스로 옮기는 전체 흐름을 이해하는 것입니다.
↓
로컬 테스트
↓
npm run build↓
Git Commit / Push
↓
Vercel 프로젝트 연결
↓
환경변수 등록
↓
Deploy
↓
운영 주소에서 기능 테스트
✅ localhost는 내 컴퓨터에서만 보이는 개발 환경입니다.
✅ 배포 전에는
npm run build로 빌드 오류를 먼저 확인합니다.✅ 코드는 GitHub에 올리고 Vercel 프로젝트와 연결할 수 있습니다.
✅ 비밀키는 코드가 아니라 Vercel 환경변수에 등록합니다.
✅ 배포 실패 시 Build Log의 첫 오류부터 확인합니다.
✅ 배포 성공 후에도 실제 운영 주소에서 핵심 기능을 다시 테스트합니다.
여기까지 왔다면 이제 바이브코딩으로 만든 프로젝트를 내 컴퓨터 안에서만 실행하는 단계를 넘어 다른 사람에게 실제 URL을 공유할 수 있습니다.
처음에는 “배포”라는 단어 자체가 어렵게 느껴지지만, 실제 흐름은 빌드 확인 → GitHub 저장 → Vercel 연결 → 환경변수 설정 → 배포 → 테스트로 반복됩니다. 이 과정을 한 번 직접 경험해두면 다음 프로젝트부터는 훨씬 자연스럽게 진행할 수 있습니다.
🔗 바이브코딩 입문 시리즈