vite build 오류 해결: 실무에서 바로 적용하는 가이드

vite build 오류 해결이 필요한 상황

vite build 오류 해결은 배포 전 빌드 단계에서 발생하는 다양한 실패를 빠르게 복구하고, 원인에 따라 설정을 수정해 정상 빌드를 되찾는 과정입니다. 이 글에서는 흔한 오류 유형별 원인 파악 방법, vite.config.js와 의존성 처리 실무 예제, 운영 환경에서 주의할 점 및 체크리스트를 제공하여 바로 적용할 수 있게 안내합니다.

vite build 오류 해결 핵심 개념

vite는 개발 서버에서 빠른 HMR을 제공하고, 빌드 시에는 Rollup을 이용해 번들링합니다. 따라서 빌드 실패는 주로 다음 영역에서 발생합니다:

• 의존성(Dependency) 문제: ESM/CJS 혼용, 외부 패키지의 빌드 필요
• 설정(Configuration) 문제: rollup 플러그인, alias, 외부화(external) 설정 오류
• 플랫폼/환경 문제: Node 버전, 환경 변수, 파일 시스템 케이스 민감성
• 번들 크기/메모리 문제: 큰 라이브러리나 동적 import 처리

정확한 원인 파악은 오류 로그(rollup 에러, unresolved import, SyntaxError 등)를 기반으로 해야 합니다. 다음 섹션에서 실무 예제와 단계별 진단 방법을 제시합니다.

vite build 오류 해결 실무 예제

아래는 흔한 사례와 실무 수정 예제입니다.

사례 1: 외부 패키지에서 CJS만 제공하여 빌드 오류가 나는 경우

• 증상: build 시 "Could not resolve" 또는 "Unexpected token" 같은 에러
• 원인: 패키지가 CommonJS 형식으로만 배포되어 Rollup이 ESM으로 처리하지 못함
• 해결: optimizeDeps.include/prebundle 또는 rollupCommonjs 플러그인 사용

예시 vite.config.js 수정:

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import commonjs from '@rollup/plugin-commonjs'

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    include: ['some-cjs-only-package']
  },
  build: {
    rollupOptions: {
      plugins: [commonjs()]
    }
  }
})

사례 2: 외부 모듈이 Node 전용 API를 사용해서 브라우저 빌드 실패

• 증상: "require('fs') is not supported" 또는 관련 내장 모듈 에러
• 해결: 해당 모듈을 서버 사이드 전용으로 분리하거나 대체 패키지 사용, rollup external 처리

예시: 특정 패키를 외부화

// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      external: ['fs', 'path']
    }
  }
})

사례 3: 변환에 실패하는 파일(예: 미처리한 JSX/TSX)로 인한 에러

• 증상: SyntaxError 또는 Unexpected token
• 해결: @vitejs/plugin-react 같은 플러그인이 설치/설정되었는지 확인, include/exclude 패턴 점검

vite build 오류 유형별 판단 기준 표

위 표를 근거로 로그를 빠르게 분류하고 조치하세요.

언제 쓰면 좋고 언제 피해야 할까

언제 쓰면 좋은가

• 배포 전 빌드에서 에러가 발생하여 빠르게 원인을 분류해야 할 때
• 외부 패키지와의 호환성 문제를 해결하고자 할 때
• 빌드 설정을 최적화하고자 하여 rollup/플러그인 조합을 조정할 때

언제 피해야 하는가

• 일시적인 개발 서버 오류(핫 리로드 문제 등)인데 빌드 설정을 광범위하게 바꾸는 경우
• 패치 성격의 임시 대응(예: 무분별한 external 처리)으로 실제 런타임 문제를 만든 경우
• 성능 영향(번들 크기 증가)을 고려하지 않고 무조건 플러그인 추가만 하는 경우

실무 체크리스트

• 오류 로그 캡처 및 주요 키워드(ex: unresolved, unexpected token, ENOENT) 정리
• Node 버전이 프로젝트 요구사항과 일치하는지 확인
• vite.config.js에서 optimizeDeps, build.rollupOptions 설정 검토
• 플러그인(@vitejs/plugin-react, commonjs 등) 설치 여부 확인
• 외부화(external) 또는 alias가 잘못 지정되지 않았는지 확인
• 의존성 패키지의 ESM/CJS 제공 여부 확인
• 캐시 재생성: node_modules/.vite 삭제 후 재빌드 시도

성능·보안·운영 주의점

성능

• 무분별한 optimizeDeps.include는 prebundle 시간이 늘어나 CI 빌드 시간이 증가할 수 있음.
• external로 처리하면 번들 크기는 작아질 수 있으나 런타임에서 해당 모듈을 로드할 수 없는 상황을 유발할 수 있음.

보안

• 외부 패치로 임시 대응(예: 특정 패키지의 빌드 스킵)은 공급망 취약점을 숨길 수 있음. 원인 패키지의 업데이트 여부를 확인하고 장기적으로는 패치 적용 권장.

운영

• CI 환경은 로컬과 다른 Node 버전/파일시스템 규약을 가질 수 있음. CI에서 재현 가능한 빌드 스크립트를 유지하세요.
• 캐시 정책(예: npm ci vs npm install, vite 캐시)으로 인해 빌드가 다르게 동작할 수 있으므로 CI에서 캐시를 명확히 관리합니다.

vite 설정 변경 예시 — 실제 적용 코드

아래는 흔한 문제를 포괄적으로 다루는 설정 예시입니다.

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import commonjs from '@rollup/plugin-commonjs'
import nodeResolve from '@rollup/plugin-node-resolve'

export default defineConfig(({mode}) => ({
  plugins: [react()],
  optimizeDeps: {
    include: ['some-cjs-only-package'],
    esbuildOptions: {
      target: 'es2020'
    }
  },
  resolve: {
    alias: {
      '@': '/src'
    }
  },
  build: {
    target: 'es2018',
    rollupOptions: {
      plugins: [nodeResolve(), commonjs()],
      external: mode === 'ssr' ? ['fs'] : []
    }
  }
}))

위 예시는 CJS 패키지 전처리, 플러그인 추가, 빌드 타깃 조정을 한 번에 보여줍니다. 환경에 따라 조합을 조정하세요.

비교: 대처 방법 선택 기준

자주 묻는 질문

Q1: vite build 오류가 나면 가장 먼저 무엇을 확인해야 하나요?

• A1: 오류 로그의 핵심 문구(예: unresolved, Unexpected token)를 확인하고, 문제가 되는 파일/모듈을 찾습니다. 다음으로 Node 버전과 vite.config.js의 플러그인/optimizeDeps 설정을 점검하세요.

Q2: optimizeDeps.include와 build.rollupOptions의 차이는 무엇인가요?

• A2: optimizeDeps.include는 개발 서버에서의 prebundle(디팬던시 전처리)을 제어합니다. build.rollupOptions는 실제 빌드(생산 번들)를 위한 설정으로, 둘을 상황에 맞게 조합해야 합니다.

Q3: 빌드에서만 발생하는 에러를 로컬에서 재현하려면 어떻게 해야 하나요?

• A3: NODE_ENV=production 또는 vite build 명령을 로컬에서 실행해보세요. 또한 CI 환경과 동일한 Node/npm 버전, 환경 변수를 맞추는 것이 재현에 도움이 됩니다.

Q4: 특정 패키지를 external로 처리해도 되나요?

• A4: 서버 사이드(SSR)나 런타임에서 해당 모듈을 제공할 수 있을 때만 external로 처리하세요. 클라이언트 번들에서 external로 처리하면 브라우저에서 로드 불가가 될 수 있습니다.

정리

• vite build 오류 해결은 로그 기반 원인 분류 후 적절한 설정 수정으로 진행합니다.
• 흔한 원인은 의존성(ESM/CJS), 설정(플러그인/alias), 환경(Node/CI)입니다.
• optimizeDeps와 rollup 옵션을 상황에 맞게 조합해 사용하세요.
• 실무 체크리스트를 통해 재현과 해결 절차를 표준화하면 재발을 줄일 수 있습니다.
• 성능·보안·운영 리스크를 고려해 임시 대응 대신 장기적 패치 전략을 세우세요.