배포 매뉴얼
전체 목차03 · 프로젝트 Import와 첫 배포
Chapter 03

프로젝트 Import와 첫 배포

최종 확인일 2026-11-04 읽는 시간 약 8분 시작하기 · 첫 배포까지

목표#

  • GitHub 저장소를 Vercel 프로젝트로 가져와(Import) 첫 배포를 완료합니다.
  • 배포 진행 과정(빌드 로그)과 결과 화면을 읽는 방법을 익힙니다.
  • git push만으로 자동 배포가 되는지 직접 확인합니다.

사전 조건#

  • 1장: GitHub에 my-app 저장소가 push되어 있습니다.
  • 2장: Vercel Import Git Repository 목록에 my-app이 보입니다.
  • (권장) 로컬에서 빌드가 성공하는지 미리 확인했습니다. JavaScript 프레임워크 프로젝트라면:

    bash
    npm install
    npm run build
팁

로컬에서 실패하는 빌드는 Vercel에서도 실패합니다. 배포 전에 로컬 빌드를 한 번 돌려 보면 문제를 훨씬 빨리 찾을 수 있습니다.


1. 저장소 Import 하기#

  1. Vercel 대시보드에서 Add New… → Project를 누릅니다.
  2. Import Git Repository 목록에서 my-app 옆의 Import 버튼을 누릅니다.
  3. Configure Project 화면으로 이동합니다.

2. Configure Project 화면 살펴보기#

대부분의 프로젝트는 아무것도 바꾸지 않고 바로 배포해도 됩니다. Vercel이 프레임워크를 자동으로 감지해 알맞은 값을 채워 줍니다.

항목설명기본값 그대로 둬도 되나요?
Project NameVercel 프로젝트 이름. 기본 주소(<이름>.vercel.app)에도 사용됩니다.대부분 그대로
Framework Preset감지된 프레임워크 (Next.js, Vite, Other 등)올바르게 감지되었는지 확인
Root Directory프로젝트가 저장소 하위 폴더에 있을 때 지정저장소 최상단에 프로젝트가 있으면 그대로
Build and Output Settings빌드 명령, 결과물 폴더, 설치 명령대부분 그대로
Environment VariablesAPI 키 등 환경 변수필요한 값이 있을 때만 입력
참고

각 항목의 자세한 설정법은 4장 빌드 설정과 5장 환경 변수에서 다룹니다. 여기서 설정하지 않아도 나중에 프로젝트 Settings에서 언제든 바꿀 수 있습니다.

중요

프로젝트가 API 키 같은 환경 변수 없이는 빌드되지 않는다면, Deploy를 누르기 전에 Environment Variables에 값을 넣어 주세요. 비워 두면 첫 배포가 실패합니다.

3. 배포하기#

  1. 설정을 확인했으면 Deploy 버튼을 누릅니다.
  2. 빌드 로그 화면이 나타나고 배포가 진행됩니다. 보통 수십 초에서 몇 분이 걸립니다.
  3. 배포가 끝나면 축하 화면과 함께 사이트 미리보기가 표시됩니다.
  4. 미리보기 이미지를 누르거나 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 영역에서 배포 정보를 볼 수 있습니다.

  1. Visit 버튼 또는 Domains에 표시된 주소를 누릅니다.
  2. 새 탭에서 사이트가 열리면 첫 배포 성공입니다. 🎉

주소가 여러 개인 이유#

배포 하나에는 여러 개의 URL이 붙습니다.

URL 종류형태 (예시)특징
프로덕션 도메인my-app.vercel.app항상 최신 Production 배포를 가리킴. 사용자에게 공유하는 주소
배포별 고유 URLmy-app-<임의문자>-<팀이름>.vercel.app특정 배포 하나에 고정. 나중에 코드가 바뀌어도 이 주소의 내용은 그대로
브랜치 URLmy-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만 하면 자동으로 배포되는지 확인해 봅니다.

  1. 로컬에서 화면에 보이는 문구 하나를 수정합니다. 예: index.html의 제목, 또는 Next.js의 app/page.tsx 문구
  2. 커밋하고 push합니다.

    bash
    git add .
    git commit -m "메인 페이지 문구 변경"
    git push
  3. Vercel 프로젝트의 Deployments 탭을 엽니다.
  4. 방금 커밋 메시지와 같은 이름의 새 배포가 Building 상태로 나타나는지 확인합니다.
  5. 상태가 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, 빌드 명령, 결과물 폴더 등을 직접 설정하는 방법을 알아봅니다.

참고 자료#