목표#
- Vercel이 프로젝트를 어떻게 빌드하는지 이해합니다.
- Framework Preset, Build Command, Output Directory, Install Command, Root Directory, Node.js 버전을 상황에 맞게 설정합니다.
- 화면 설정 대신
vercel.json파일로 설정을 코드로 관리하는 방법을 알아 둡니다.
사전 조건#
- 3장에서 프로젝트를 Import했습니다.
package.json의scripts를 읽을 수 있습니다. (JavaScript 프레임워크 프로젝트인 경우)
1. Vercel의 빌드 과정#
Vercel은 배포할 때마다 아래 순서로 작업합니다. 이 장의 설정은 각 단계를 바꾸는 것입니다.
① 코드 내려받기 → ② Install Command 실행 → ③ Build Command 실행 → ④ Output Directory 업로드
(Root Directory 기준) (예: npm install) (예: npm run build) (예: dist/)2. 설정 위치#
- 처음 Import할 때: Configure Project 화면의 Build and Output Settings
- Import한 뒤: 프로젝트 Settings → Build and Deployment
빌드 설정을 바꿔도 이미 끝난 배포에는 적용되지 않습니다. 저장 후 새로 push하거나, Deployments 탭에서 최신 배포의 ⋯ → Redeploy를 눌러야 반영됩니다.
3. Framework Preset#
Vercel은 저장소의 파일(package.json의 의존성, 설정 파일 등)을 보고 프레임워크를 자동으로 감지합니다. 감지된 프레임워크에 맞춰 나머지 값의 기본값이 정해집니다.
| 프레임워크 | 기본 Build Command | 기본 Output Directory |
|---|---|---|
| Next.js | next build | 자동 처리 (설정 불필요) |
| Vite (React, Vue 등) | vite build 또는 npm run build | dist |
| Create React App | react-scripts build | build |
| Astro | astro build | dist |
| Nuxt | nuxt build | 자동 처리 |
| SvelteKit | vite build | 자동 처리 |
| Other (순수 HTML 등) | 없음 | public 폴더가 있으면 public, 없으면 저장소 최상단 |
순수 HTML 사이트라면 Framework Preset을 Other로 두고, index.html이 저장소 최상단(또는 public/ 폴더)에 있으면 별도 설정 없이 배포됩니다.
프레임워크가 잘못 감지되면(예: Vite 프로젝트가 Other로 감지) 빌드 명령이 실행되지 않거나 엉뚱한 폴더가 배포되어 404가 납니다. Import 화면에서 Framework Preset을 꼭 확인하세요.
4. Build / Output / Install Command 직접 지정하기#
기본값을 바꾸려면 항목 오른쪽의 Override 스위치를 켜고 값을 입력합니다.
4-1. Build Command#
결과물을 만드는 명령입니다. 보통 package.json의 build 스크립트를 실행합니다.
// package.json
{
"scripts": {
"build": "vite build"
}
}| 이런 경우 | 설정 예시 |
|---|---|
| 빌드 스크립트 이름이 다름 | npm run build:prod |
| 빌드 전에 다른 작업이 필요 | npm run generate && npm run build |
| 빌드가 필요 없는 정적 사이트 | Override 켜고 빈칸 |
4-2. Output Directory#
빌드가 끝난 뒤 실제로 인터넷에 올릴 폴더입니다. 이 폴더 안에 index.html이 있어야 합니다.
- 로컬에서
npm run build를 실행한 뒤 새로 생긴 폴더 이름을 확인하면 됩니다. (예:dist,build,out)
4-3. Install Command#
의존성을 설치하는 명령입니다. Vercel은 잠금 파일(lock file) 을 보고 패키지 관리자를 자동으로 고릅니다.
| 저장소에 있는 파일 | 사용되는 패키지 관리자 |
|---|---|
package-lock.json | npm |
yarn.lock | Yarn |
pnpm-lock.yaml | pnpm |
bun.lock / bun.lockb | Bun |
잠금 파일은 반드시 커밋하고, 한 저장소에는 한 종류만 두세요. 잠금 파일이 없거나 여러 개면 로컬과 다른 버전이 설치되어 "로컬에선 되는데 Vercel에선 안 되는" 문제가 생깁니다.
5. Root Directory (하위 폴더·모노레포)#
프로젝트가 저장소 최상단이 아니라 하위 폴더에 있을 때 지정합니다.
my-repo/
├── backend/
└── frontend/ ← 배포할 프로젝트 (package.json이 여기 있음)
├── package.json
└── src/- Root Directory 옆의 Edit를 누릅니다.
frontend폴더를 선택하고 Continue를 누릅니다.- 이제 Install/Build Command는
frontend/폴더 안에서 실행됩니다.
하나의 저장소에 프론트엔드가 여러 개 있다면(모노레포), 같은 저장소를 여러 번 Import하고 프로젝트마다 다른 Root Directory를 지정하면 됩니다.
모노레포에서 frontend/ 바깥 파일이 바뀔 때도 매번 빌드되는 것을 막으려면, Settings → Git → Ignored Build Step 설정을 활용할 수 있습니다.
6. Node.js 버전#
Vercel은 기본적으로 지원하는 Node.js LTS 버전 중 하나로 빌드합니다. 로컬과 버전이 다르면 빌드가 실패할 수 있습니다.
방법 A. 대시보드에서 지정#
Settings → Build and Deployment → Node.js Version에서 버전을 선택합니다.
방법 B. package.json에서 지정 (권장)#
{
"engines": {
"node": "22.x"
}
}package.json의 engines.node가 있으면 대시보드 설정보다 우선 적용됩니다. 코드와 함께 버전이 기록되므로 팀원 모두 같은 버전을 쓰기 쉽습니다. 사용 가능한 버전은 Vercel 지원 Node.js 버전에서 확인하세요.
로컬 버전 확인:
node --version7. vercel.json으로 설정 관리하기 (선택)#
저장소 최상단(또는 Root Directory)에 vercel.json을 두면 설정을 코드로 관리할 수 있습니다. 파일 설정은 대시보드 설정보다 우선합니다.
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"buildCommand": "npm run build",
"outputDirectory": "dist",
"installCommand": "npm ci"
}자주 쓰는 예: SPA 새로고침 404 해결#
React Router 같은 클라이언트 라우팅을 쓰는 Vite/CRA 프로젝트는 /about 같은 주소에서 새로고침하면 404가 납니다. 모든 경로를 index.html로 보내면 해결됩니다.
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}Next.js, Nuxt처럼 자체 라우팅을 처리하는 프레임워크에는 위 rewrites를 넣지 마세요. 오히려 페이지가 깨질 수 있습니다.
자주 쓰는 예: 주소 이동(redirect)#
{
"redirects": [
{ "source": "/old-page", "destination": "/new-page", "permanent": true }
]
}확인 방법#
문제 해결#
| 증상 | 원인과 해결 |
|---|---|
No Output Directory named "dist" found | Output Directory 이름이 실제와 다름 → 로컬 빌드 결과 폴더 이름으로 수정 |
배포 성공 후 404: NOT_FOUND | Framework Preset 오감지 또는 Output Directory 오류 → 3·4단계 재확인 |
/about에서 새로고침하면 404 (SPA) | 7단계의 rewrites 추가 |
The engine "node" is incompatible | Node.js 버전 불일치 → 6단계 참고 |
하위 폴더 프로젝트에서 package.json 없음 오류 | Root Directory 미설정 → 5단계 참고 |
더 많은 사례는 9장 문제 해결을 참고하세요.
다음 단계#
➡️ 5장. 환경 변수: API 키 같은 비밀 값을 코드에 넣지 않고 Vercel에 안전하게 설정합니다.