콘텐츠로 이동

Vite 빌드

개요

개발 서버가 빠른 것과 별개로, 배포할 때는 vite build 명령으로 프로덕션 번들을 만들어야 해요. 기본적으로 <root>/index.html을 엔트리로 삼아 정적 호스팅에 올리기 좋은 앱 번들을 만들어요. 개발은 ESM·HMR로, 배포는 번들로 — 개발 속도와 배포 성능을 따로 잡는 구조죠.

핵심 개념

  • 브라우저 호환성 — 기본 배포 번들은 최신 기준(Baseline Widely Available)을 겨냥해요. 현재 메이저 버전 기준 Chrome/Edge 111+, Firefox 114+, Safari 16.4+ 정도를 기본 지원해요. build.target으로 커스텀할 수 있고, 가장 낮은 타깃은 es2015예요. 다만 Vite는 구문 변환만 하고 폴리필은 다루지 않아요. 폴리필이 필요하면 별도 서비스나 @vitejs/plugin-legacy로 찾아야 하죠.
  • public base path — 하위 경로에 배포한다면 base 설정으로 모든 에셋 경로를 통째로 다시 써요. vite build --base=/my/public/path/처럼 CLI 플래그로도 되고요. JS import URL, CSS url(), HTML 참조가 모두 자동으로 조정돼요. 배포 위치를 미리 모른다면 base: './'로 상대 경로를 쓸 수도 있어요.

// vite.config.js — 하위 경로 배포를 위한 base 예시
export default defineConfig({
  base: '/wiki/',        // 모든 에셋 경로를 /wiki/ 아래로 다시 쓴다
});
- 빌드 커스터마이징 — build.rolldownOptions(현재 빌드 번들러인 Rolldown 옵션)로 출력 방식을 직접 조정할 수 있어요. 청크를 어떻게 쪼갤지(codeSplitting), 어떤 플러그인을 빌드에만 적용할지 등을 제어하죠. - 멀티 페이지 앱(MPA) — .html 파일이 여러 개면 build.rolldownOptions.input에 여러 엔트리를 지정하면 돼요. 개발 중엔 그냥 /nested/로 접근하면 정적 서버처럼 동작해요. - 라이브러리 모드 — 배포용 라이브러리를 만들 땐 build.lib 옵션을 써요. 이때 react나 vue 같은 의존성은 번들에 넣지 않도록 external로 빼야 해요. - 모드와 환경변수 — 빌드는 --mode로 모드를 골라 .env.[mode] 파일을 읽어요. 개발(development)과 프로덕션(production)이 기본 모드죠. 코드에서는 import.meta.env.*로 읽고, VITE_ 접두사를 붙인 변수만 노출돼요. 예를 들어 API 주소 같은 걸 모드별로 다르게 넣을 수 있어요.

실제 적용(데이터스케쳐스 관점)

캔버스는 정적 호스팅에 올리는 순수 클라이언트 앱이라 vite build가 그대로 배포 산출물을 만들어요. 이때 신경 쓸 지점이 두 가지 정도 있어요.

하나는 base 경로예요. 위키를 /wiki/ 하위 경로에 배포하듯, 캔버스도 CDN이나 특정 하위 경로에 실릴 수 있어서 배포 위치에 맞는 base 설정이 중요해요. base를 상대 경로(base: './')로 두면 어디에 놓든 에셋 경로가 맞아 떨어져서, 경로를 미리 모를 때 편리해요.

다른 하나는 CSP/정적 배포 특성이에요. 정적 사이트는 배포 후 이전 빌드의 에셋이 사라지면, 예전 에셋을 참조하던 사용자에게 import 오류가 날 수 있어요. Vite는 vite:preloadError 이벤트로 이 상황을 감지하게 해주고, 상황에 따라 새로고침 같은 처리를 할 수 있게 해요. 배포 자동화가 필요하면 vite build --watch나 watcher 설정으로 파일이 바뀔 때마다 다시 빌드할 수도 있어요.

환경변수 헷갈리기 쉬우니 하나만 기억해 두면 돼요. VITE_ 접두사가 붙은 변수만 빌드 타임에 클라이언트 코드로 주입돼요. API 주소 같은 걸 .env.development와 .env.production에 나눠 두고 모드에 따라 갈아 끼우는 게 전형적인 패턴이죠. vite build --mode staging처럼 커스텀 모드를 만들 수도 있어요.

더 알아보기