배포 매뉴얼
전체 목차04 · 빌드 설정
Chapter 04

빌드 설정

최종 확인일 2026-11-04 읽는 시간 약 8분 설정 · 빌드와 환경 변수

목표#

  • Vercel이 프로젝트를 어떻게 빌드하는지 이해합니다.
  • Framework Preset, Build Command, Output Directory, Install Command, Root Directory, Node.js 버전을 상황에 맞게 설정합니다.
  • 화면 설정 대신 vercel.json 파일로 설정을 코드로 관리하는 방법을 알아 둡니다.

사전 조건#

  • 3장에서 프로젝트를 Import했습니다.
  • package.json의 scripts를 읽을 수 있습니다. (JavaScript 프레임워크 프로젝트인 경우)

1. Vercel의 빌드 과정#

Vercel은 배포할 때마다 아래 순서로 작업합니다. 이 장의 설정은 각 단계를 바꾸는 것입니다.

output
① 코드 내려받기 → ② 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.jsnext build자동 처리 (설정 불필요)
Vite (React, Vue 등)vite build 또는 npm run builddist
Create React Appreact-scripts buildbuild
Astroastro builddist
Nuxtnuxt build자동 처리
SvelteKitvite 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 스크립트를 실행합니다.

JSON
// 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.jsonnpm
yarn.lockYarn
pnpm-lock.yamlpnpm
bun.lock / bun.lockbBun
팁

잠금 파일은 반드시 커밋하고, 한 저장소에는 한 종류만 두세요. 잠금 파일이 없거나 여러 개면 로컬과 다른 버전이 설치되어 "로컬에선 되는데 Vercel에선 안 되는" 문제가 생깁니다.


5. Root Directory (하위 폴더·모노레포)#

프로젝트가 저장소 최상단이 아니라 하위 폴더에 있을 때 지정합니다.

output
my-repo/
├── backend/
└── frontend/        ← 배포할 프로젝트 (package.json이 여기 있음)
    ├── package.json
    └── src/
  1. Root Directory 옆의 Edit를 누릅니다.
  2. frontend 폴더를 선택하고 Continue를 누릅니다.
  3. 이제 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에서 지정 (권장)#

JSON
{
  "engines": {
    "node": "22.x"
  }
}
참고

package.json의 engines.node가 있으면 대시보드 설정보다 우선 적용됩니다. 코드와 함께 버전이 기록되므로 팀원 모두 같은 버전을 쓰기 쉽습니다. 사용 가능한 버전은 Vercel 지원 Node.js 버전에서 확인하세요.

로컬 버전 확인:

bash
node --version

7. vercel.json으로 설정 관리하기 (선택)#

저장소 최상단(또는 Root Directory)에 vercel.json을 두면 설정을 코드로 관리할 수 있습니다. 파일 설정은 대시보드 설정보다 우선합니다.

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로 보내면 해결됩니다.

JSON
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}
주의

Next.js, Nuxt처럼 자체 라우팅을 처리하는 프레임워크에는 위 rewrites를 넣지 마세요. 오히려 페이지가 깨질 수 있습니다.

자주 쓰는 예: 주소 이동(redirect)#

JSON
{
  "redirects": [
    { "source": "/old-page", "destination": "/new-page", "permanent": true }
  ]
}

확인 방법#

문제 해결#

증상원인과 해결
No Output Directory named "dist" foundOutput Directory 이름이 실제와 다름 → 로컬 빌드 결과 폴더 이름으로 수정
배포 성공 후 404: NOT_FOUNDFramework Preset 오감지 또는 Output Directory 오류 → 3·4단계 재확인
/about에서 새로고침하면 404 (SPA)7단계의 rewrites 추가
The engine "node" is incompatibleNode.js 버전 불일치 → 6단계 참고
하위 폴더 프로젝트에서 package.json 없음 오류Root Directory 미설정 → 5단계 참고

더 많은 사례는 9장 문제 해결을 참고하세요.

다음 단계#

➡️ 5장. 환경 변수: API 키 같은 비밀 값을 코드에 넣지 않고 Vercel에 안전하게 설정합니다.

참고 자료#