목표#
- GitHub 저장소를 Vercel 프로젝트로 가져와(Import) 첫 배포를 완료합니다.
- 배포 진행 과정(빌드 로그)과 결과 화면을 읽는 방법을 익힙니다.
git push만으로 자동 배포가 되는지 직접 확인합니다.
사전 조건#
- 1장: GitHub에
my-app저장소가 push되어 있습니다. - 2장: Vercel Import Git Repository 목록에
my-app이 보입니다. (권장) 로컬에서 빌드가 성공하는지 미리 확인했습니다. JavaScript 프레임워크 프로젝트라면:
npm install npm run build
로컬에서 실패하는 빌드는 Vercel에서도 실패합니다. 배포 전에 로컬 빌드를 한 번 돌려 보면 문제를 훨씬 빨리 찾을 수 있습니다.
1. 저장소 Import 하기#
- Vercel 대시보드에서 Add New… → Project를 누릅니다.
- Import Git Repository 목록에서
my-app옆의 Import 버튼을 누릅니다. - Configure Project 화면으로 이동합니다.
2. Configure Project 화면 살펴보기#
대부분의 프로젝트는 아무것도 바꾸지 않고 바로 배포해도 됩니다. Vercel이 프레임워크를 자동으로 감지해 알맞은 값을 채워 줍니다.
| 항목 | 설명 | 기본값 그대로 둬도 되나요? |
|---|---|---|
| Project Name | Vercel 프로젝트 이름. 기본 주소(<이름>.vercel.app)에도 사용됩니다. | 대부분 그대로 |
| Framework Preset | 감지된 프레임워크 (Next.js, Vite, Other 등) | 올바르게 감지되었는지 확인 |
| Root Directory | 프로젝트가 저장소 하위 폴더에 있을 때 지정 | 저장소 최상단에 프로젝트가 있으면 그대로 |
| Build and Output Settings | 빌드 명령, 결과물 폴더, 설치 명령 | 대부분 그대로 |
| Environment Variables | API 키 등 환경 변수 | 필요한 값이 있을 때만 입력 |
프로젝트가 API 키 같은 환경 변수 없이는 빌드되지 않는다면, Deploy를 누르기 전에 Environment Variables에 값을 넣어 주세요. 비워 두면 첫 배포가 실패합니다.
3. 배포하기#
- 설정을 확인했으면 Deploy 버튼을 누릅니다.
- 빌드 로그 화면이 나타나고 배포가 진행됩니다. 보통 수십 초에서 몇 분이 걸립니다.
- 배포가 끝나면 축하 화면과 함께 사이트 미리보기가 표시됩니다.
- 미리보기 이미지를 누르거나 Continue to Dashboard를 눌러 프로젝트 화면으로 이동합니다.
빌드 로그는 이런 순서로 진행됩니다#
| 단계 | 로그에서 보이는 내용 (예시) |
|---|---|
| 1. 코드 내려받기 | Cloning github.com/<USER>/my-app (Branch: main, Commit: abc1234) |
| 2. 의존성 설치 | Running "install" command: npm install |
| 3. 빌드 | Running "npm run build" |
| 4. 결과물 업로드 | Deploying outputs... |
| 5. 완료 | Deployment completed |
빌드가 실패하면 로그 마지막 부분에 빨간색 오류가 표시됩니다. 9장 문제 해결을 참고하세요.
4. 배포된 사이트 확인하기#
프로젝트 화면(Overview)의 Production Deployment 영역에서 배포 정보를 볼 수 있습니다.
- Visit 버튼 또는 Domains에 표시된 주소를 누릅니다.
- 새 탭에서 사이트가 열리면 첫 배포 성공입니다. 🎉
주소가 여러 개인 이유#
배포 하나에는 여러 개의 URL이 붙습니다.
| URL 종류 | 형태 (예시) | 특징 |
|---|---|---|
| 프로덕션 도메인 | my-app.vercel.app | 항상 최신 Production 배포를 가리킴. 사용자에게 공유하는 주소 |
| 배포별 고유 URL | my-app-<임의문자>-<팀이름>.vercel.app | 특정 배포 하나에 고정. 나중에 코드가 바뀌어도 이 주소의 내용은 그대로 |
| 브랜치 URL | my-app-git-<브랜치>-<팀이름>.vercel.app | 해당 브랜치의 최신 배포를 가리킴 (6장) |
my-app.vercel.app이 이미 다른 사람이 쓰는 이름이면 Vercel이 my-app-<임의문자>.vercel.app처럼 다른 주소를 자동으로 붙입니다. 원하는 주소로 바꾸려면 7장 커스텀 도메인을 참고하세요.
Vercel은 기본적으로 배포별 고유 URL과 Preview URL에 접속 보호(Deployment Protection) 를 적용합니다. 이 주소들은 Vercel에 로그인한 팀 구성원만 볼 수 있고, 다른 사람이 열면 로그인 화면이 나옵니다. 외부에 공유할 때는 프로덕션 도메인(my-app.vercel.app)을 사용하세요.
5. 자동 배포 확인하기#
이제 GitHub와 Vercel이 연결되었습니다. 코드를 고치고 push만 하면 자동으로 배포되는지 확인해 봅니다.
- 로컬에서 화면에 보이는 문구 하나를 수정합니다. 예:
index.html의 제목, 또는 Next.js의app/page.tsx문구 커밋하고 push합니다.
git add . git commit -m "메인 페이지 문구 변경" git push- Vercel 프로젝트의 Deployments 탭을 엽니다.
- 방금 커밋 메시지와 같은 이름의 새 배포가 Building 상태로 나타나는지 확인합니다.
- 상태가 Ready가 되면
my-app.vercel.app을 새로고침해 변경된 문구를 확인합니다.
GitHub 저장소 화면에서도 배포 상태를 볼 수 있습니다. 커밋 옆에 노란 점(진행 중), 초록 체크(성공), 빨간 X(실패)가 표시되고, 누르면 Vercel 배포 화면으로 이동합니다.
6. 프로젝트 대시보드 둘러보기#
| 탭 | 하는 일 |
|---|---|
| Overview | 현재 Production 배포, 도메인, 최근 활동 |
| Deployments | 모든 배포 목록. 상태·브랜치·커밋 확인, 재배포·롤백 |
| Logs | 실행 중 발생한 로그 (서버 함수 사용 시) |
| Analytics / Speed Insights | 방문자·성능 통계 (별도 활성화 필요) |
| Settings | 빌드 설정, 환경 변수, 도메인, Git 연결 등 모든 설정 |
확인 방법#
문제 해결#
| 증상 | 확인할 것 |
|---|---|
빌드 로그 끝에 Error / exited with 1 | 로그에서 첫 번째 오류 메시지를 찾아 9장 참고 |
배포는 성공했는데 404: NOT_FOUND | 결과물 폴더(Output Directory) 설정 → 4장 |
| 배포는 성공했는데 화면이 하얗게 나옴 | 브라우저 개발자 도구(F12) Console 탭 오류 확인, 환경 변수 누락 여부 → 5장 |
| push해도 새 배포가 생기지 않음 | push한 브랜치, GitHub App 권한 → 9장 |
다음 단계#
➡️ 4장. 빌드 설정: Framework Preset, 빌드 명령, 결과물 폴더 등을 직접 설정하는 방법을 알아봅니다.