공유 옵션

root

• 타입: string
• 기본값: process.cwd()

프로젝트 루트 디렉터리(여기에 index.html이 위치함)입니다. 절대 경로 또는 현재 작업 디렉터리를 기준으로 한 상대 경로가 될 수 있습니다.

자세한 내용은 프로젝트 루트를 참조하세요.

base

• 타입: string
• 기본값: /
• 관련 정보: server.origin

개발 또는 프로덕션에서 제공될 때 기본 공개 경로입니다. 유효한 값은 다음과 같습니다:

• 절대 URL 경로명, 예: /foo/
• 전체 URL, 예: https://foo.com/ (개발 시 원본 부분은 사용되지 않음)
• 빈 문자열 또는 ./ (내장 배포용)

자세한 내용은 공개 기본 경로를 참조하세요.

mode

• 타입: string
• 기본값: serve의 경우 'development', build의 경우 'production'

이 설정을 구성하면 서빙과 빌드 모두에 대한 기본 모드를 무시합니다. 이 값은 명령 줄 --mode 옵션을 통해 재정의할 수도 있습니다.

자세한 내용은 환경 변수 및 모드를 참조하세요.

define

• 타입: Record<string, any>

전역 상수 대체를 정의합니다. 항목은 개발 중에 전역으로 정의되고 빌드 중에 정적으로 대체됩니다.

Vite는 대체를 수행하기 위해 esbuild defines를 사용하므로 값 표현식은 문자열이어야 하며 JSON 직렬화 가능한 값 (null, boolean, number, string, array 또는 object) 또는 단일 식별자여야 합니다. 문자열이 아닌 값의 경우 Vite는 자동으로 JSON.stringify를 사용하여 문자열로 변환합니다.

예시:

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify('v1.0.0'),
    __API_URL__: 'window.__backend_api_url',
  },
})

참고

TypeScript 사용자는 타입 체크와 Intellisense를 얻으려면 env.d.ts 또는 vite-env.d.ts 파일에 타입 선언을 추가해야 합니다.

예시:

// vite-env.d.ts
declare const __APP_VERSION__: string

plugins

• 타입: (Plugin | Plugin[] | Promise<Plugin | Plugin[]>)[]

사용할 플러그인 배열입니다. 거짓인 플러그인은 무시되며 플러그인 배열은 평탄화됩니다. 프로미스가 반환되면 실행되기 전에 해결됩니다. Vite 플러그인에 대한 자세한 내용은 Plugin API를 참조하세요.

publicDir

• 타입: string | false
• 기본값: "public"

일반 정적 에셋으로 제공할 디렉터리입니다. 이 디렉터리의 파일은 개발 중에 /에서 제공되고 빌드 중에는 outDir의 루트로 복사되며 변형 없이 항상 제공되거나 복사됩니다. 값은 절대 파일 시스템 경로 또는 프로젝트 루트를 기준으로 한 경로일 수 있습니다.

publicDir를 false로 정의하면 이 기능이 비활성화됩니다.

자세한 내용은 public 디렉터리를 참조하세요.

cacheDir

• 타입: string
• 기본값: "node_modules/.vite"

캐시 파일을 저장할 디렉터리입니다. 이 디렉터리의 파일은 미리 번들링된 종속성 또는 Vite에서 생성한 기타 캐시 파일로 개선될 수 있습니다. 캐시 파일을 다시 생성하려면 --force 플래그를 사용하거나 디렉터리를 수동으로 삭제할 수 있습니다. 값은 절대 파일 시스템 경로 또는 프로젝트 루트를 기준으로 한 경로일 수 있습니다. package.json이 감지되지 않을 때 기본값은 .vite입니다.

resolve.alias

• 타입: Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

@rollup/plugin-alias에 전달될 것입니다. 객체 또는 { find, replacement, customResolver } 쌍의 배열이 될 수 있습니다.

파일 시스템 경로에 별칭을 지정할 때는 항상 절대 경로를 사용하세요. 상대 별칭 값은 그대로 사용되며 파일 시스템 경로로 해결되지 않습니다.

더 고급 사용자 지정 해결은 플러그인을 통해 달성할 수 있습니다.

SSR 사용

SSR 외부 종속성에 대한 별칭을 구성한 경우 실제 node_modules 패

키지에 별칭을 지정해야 할 수 있습니다. Yarn 및 pnpm은 npm: 접두사를 사용하여 별칭을 지정할 수 있습니다.

resolve.dedupe

• 타입: string[]

앱에 동일한 종속성의 중복된 사본이 있는 경우 (일반적으로 호이스팅 또는 모노 레포지토리에서 링크된 패키지 때문에 발생함)이 옵션을 사용하여 항상 동일한 사본으로 해결하도록 Vite에 지시할 수 있습니다.

SSR + ESM

SSR 빌드의 경우 ESM 빌드 출력에서는 build.rollupOptions.output로 구성된 ESM에 대해 중복 제거가 작동하지 않습니다. ESM이 모듈 로딩에 대한 더 나은 플러그인 지원을 할 때까지 CJS 빌드 출력을 사용하는 것이 해결 방법입니다.

resolve.conditions

• 타입: string[]

패키지에서 조건부 내보내기를 해결할 때 추가로 허용되는 조건입니다.

조건부 내보내기를 가진 패키지는 다음과 같은 package.json의 exports 필드를 가질 수 있습니다:

json

{
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js"
    }
  }
}

여기서 import 및 require는 "조건"입니다. 조건은 중첩될 수 있으며 가장 구체적인 것부터 가장 일반적인 것으로 지정해야 합니다.

Vite에는 "허용된 조건" 목록이 있으며, Vite는 허용된 목록에 있는 첫 번째 조건을 일치시킵니다. 기본 허용된 조건은 현재 모드에 따라 import, module, browser, default 및 production/development입니다. resolve.conditions 구성 옵션을 사용하여 추가 허용된 조건을 지정할 수 있습니다.

하위 경로 내보내기 해결

"/"로 끝나는 내보내기 키는 Node에서 사용이 중지되었으며 잘 작동하지 않을 수 있습니다. 패키지 작성자에게 연락하여 * 하위 경로 패턴을 사용하도록 요청하세요.

resolve.mainFields

• 타입: string[]
• 기본값: ['browser', 'module', 'jsnext:main', 'jsnext']

패키지의 진입점을 해결할 때 시도할 package.json의 필드 목록입니다. 조건부 내보내기로부터 해결된 경우 이것은 낮은 우선순위를 가집니다: 진입점이 exports에서 성공적으로 해결되면 메인 필드가 무시됩니다.

resolve.extensions

• 타입: string[]
• 기본값: ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']

확장자를 생략한 가져오기에 대한 시도할 파일 확장자 목록입니다. 사용자 지정 가져오기 유형 (예: .vue)에 대해 확장자를 생략하지 않는 것은 권장되지 않습니다. IDE 및 유형 지원과 충돌할 수 있습니다.

resolve.preserveSymlinks

• 타입: boolean
• 기본값: false

이 설정을 활성화하면 Vite는 원본 파일 경로 (즉, 심볼릭 링크를 따르기 전의 경로)를 사용하여 파일 식별을 결정하고 실제 파일 경로 (즉, 심볼릭 링크를 따른 후의 경로)를 사용하지 않습니다.

html.cspNonce

• 타입: string
• 관련 정보: 콘텐츠 보안 정책 (CSP)

스크립트/스타일 태그 생성 시 사용할 논스 값 플레이스홀더입니다. 이 값을 설정하면 논스 값을 사용하여 메타 태그를 생성합니다.

css.modules

CSS 모듈 동작을 구성합니다. 이 옵션은 postcss-modules로 전달됩니다.

이 옵션은 라이트닝 CSS를 사용할 때는 효과가 없습니다. 활성화된 경우 대신 css.lightningcss.cssModules를 사용해야 합니다.

css.postcss

인라인 PostCSS 설정 또는 사용자 지정 디렉토리를 지정하여 PostCSS 설정을 검색합니다 (기본값은 프로젝트 루트).

인라인 PostCSS 설정의 경우 postcss.config.js와 동일한 형식을 기대합니다. 그러나 plugins 속성의 경우 배열 형식만 사용할 수 있습니다.

검색은 postcss-load-config를 사용하여 수행되며 지원되는 설정 파일 이름만 로드됩니다.

참고: 인라인 구성이 제공된 경우 Vite는 다른 PostCSS 구성 소스를 검색하지 않습니다.

css.preprocessorOptions

CSS 전처리기에 전달할 옵션을 지정합니다. 파일 확장자가 옵션의 키로 사용됩니다. 각 전처리기에 대한 지원되는 옵션은 해당 문서에서 확인할 수 있습니다.

예:

export default defineConfig({
  css: {
    preprocessorOptions: {
      less: {
        math: 'parens-division',
      },
      styl: {
        define: {
          $specialColor: new stylus.nodes.RGBA(51, 197, 255, 1),
        },
      },
    },
  },
})

css.preprocessorOptions[extension].additionalData

이 옵션은 각 스타일 내용에 대해 추가 코드를 주입하는 데 사용될 수 있습니다. 실제 스타일을 포함하고 변수가 아닌 경우 최종 번들에서 해당 스타일이 중복될 수 있습니다.

예:

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `$injectedColor: orange;`,
      },
    },
  },
})

css.preprocessorMaxWorkers

• 실험적: 피드백 제공
• 타입: number | true
• 기본값: 0 (어떠한 워커도 생성하지 않고 메인 스레드에서 실행)

이 옵션이 설정된 경우 CSS 전처리기는 가능한 경우 워커에서 실행됩니다. true는 CPU 수에서 1을 뺀 값입니다.

css.devSourcemap

• 실험적: 피드백 제공
• 타입: boolean
• 기본값: false

개발 중에 소스맵을 활성화할지 여부입니다.

css.transformer

• 실험적: 피드백 제공
• 타입: 'postcss' | 'lightningcss'
• 기본값: 'postcss'

CSS 처리에 사용할 엔진을 선택합니다. 자세한 내용은 라이트닝 CSS를 확인하세요.

css.lightningcss

• 실험적: 피드백 제공
• 타입:

import type {
  CSSModulesConfig,
  Drafts,
  Features,
  NonStandard,
  PseudoClasses,
  Targets,
} from 'lightningcss'

{
  targets?: Targets
  include?: Features
  exclude?: Features
  drafts?: Drafts
  nonStandard?: NonStandard
  pseudoClasses?: PseudoClasses
  unusedSymbols?: string[]
  cssModules?: CSSModulesConfig,
  // ...
}

라이트닝 CSS를 구성합니다. 전체 변환 옵션은 라이트닝 CSS 저장소에서 확인할 수 있습니다.

json.namedExports

• 타입: boolean
• 기본값: true

.json 파일에서 명명된 import를 지원할지 여부입니다.

json.stringify

• 타입: boolean
• 기본값: false

true로 설정하면 가져온 JSON이 export default JSON.parse("...")으로 변환됩니다. 특히 JSON 파일이 큰 경우에는 Object literals보다 훨씬 더 성능이 우수합니다.

이를 활성화하면 명명된 import가 비활성화됩니다.

esbuild

• 타입: ESBuildOptions | false

ESBuildOptions은 esbuild의 자체 변환 옵션을 확장합니다. 가장 일반적인 사용 사례는 JSX를 사용자 정의하는 것입니다.

기본적으로 esbuild는 ts, jsx, tsx 파일에 적용됩니다. 이를 사용자 지정하려면 esbuild.include와 esbuild.exclude을 사용할 수 있습니다. 이는 정규식, picomatch 패턴 또는 이들의 배열일 수 있습니다.

또한 esbuild에 의해 변환된 모든 파일에 JSX 헬퍼 임포트를 자동으로 주입하려면 esbuild.jsxInject를 사용할 수 있습니다.

build.minify가 true로 설정된 경우 기본적으로 모든 최소화 최적화가 적용됩니다. 이를 비활성화하려면 esbuild.minifyIdentifiers, esbuild.minifySyntax, 또는 esbuild.minifyWhitespace 중 하나의 옵션을 false로 설정하면 됩니다. esbuild의 esbuild.minify 옵션을 override할 수 없다는 점에 유의하세요.

esbuild 변환을 비활성화하려면 false로 설정합니다.

assetsInclude

• 타입: string | RegExp | (string | RegExp)[]
• 관련 자료: 정적 자산 처리

정적 자산으로 처리할 추가 picomatch 패턴을 지정합니다. 이렇게 하면:

• HTML에서 참조되거나 직접 fetch 또는 XHR을 통해 요청될 때 플러그인 변환 파이프라인에서 제외됩니다.
• JS에서 가져오면 해결된 URL 문자열이 반환됩니다 (이를 덮어쓸 경우 enforce: 'pre' 플러그인이 다르게 처리하도록 할 수 있습니다).

내장 자산 유형 목록은 여기에서 찾을 수 있습니다.

예:

export default defineConfig({
  assetsInclude: ['**/*.gltf'],
})

logLevel

• 타입: 'info' | 'warn' | 'error' | 'silent'

콘솔 출력의 상세도를 조정합니다. 기본값은 'info'입니다.

customLogger

• 타입:

  interface Logger {
    info(msg: string, options?: LogOptions): void
    warn(msg: string, options?: LogOptions): void
    warnOnce(msg: string, options?: LogOptions): void
    error(msg: string, options?: LogErrorOptions): void
    clearScreen(type: LogType): void
    hasErrorLogged(error: Error | RollupError): boolean
    hasWarned: boolean
  }

메시지를 로깅하는 데 사용자 지정 로거를 사용합니다. Vite의 createLogger API를 사용하여 기본 로거를 가져온 다음 메시지를 변경하거나 특정 경고를 필터링하는 등 사용자 정의할 수 있습니다.

예:

import { createLogger, defineConfig } from 'vite'

const logger = createLogger()
const loggerWarn = logger.warn

logger.warn = (msg, options) => {
  // 빈 CSS 파일 경고 무시
  if (msg.includes('vite:css') && msg.includes(' is empty')) return
  loggerWarn(msg, options)
}

export default defineConfig({
  customLogger: logger,
})

clearScreen

• 타입: boolean
• 기본값: true

특정 메시지를 로깅할 때 Vite가 터미널 화면을 지우지 않도록 false로 설정합니다. 명령 줄에서는 --clearScreen false를 사용합니다.

envDir

• 타입: string
• 기본값: root

.env 파일이 로드되는 디렉토리입니다. 절대 경로이거나 프로젝트 루트를 기준으로 한 상대 경로일 수 있습니다.

환경 파일에 대한 자세한 내용은 여기를 참조하십시오.

envPrefix

• 타입: string | string[]
• 기본값: VITE_

envPrefix로 시작하는 환경 변수는 클라이언트 소스 코드에서 import.meta.env를 통해 노출됩니다.

보안 참고:

envPrefix를 ''로 설정하면 모든 환경 변수가 노출되어 민감한 정보가 누출될 수 있습니다. Vite는 ''을 감지하면 오류를 throw합니다.

접두어가 없는 변수를 노출하려면 define을 사용하여 노출할 수 있습니다:

define: {
  'import.meta.env.ENV_VARIABLE': JSON.stringify(process.env.ENV_VARIABLE)
}

appType

• 타입: 'spa' | 'mpa' | 'custom'
• 기본값: 'spa'

당신의 애플리케이션이 단일 페이지 애플리케이션(SPA), 다중 페이지 애플리케이션(MPA), 또는 사용자 정의 애플리케이션(SSR 및 사용자 정의 HTML 처리 프레임워크)인지 여부에 관계없이 다음을 따르십시오:

• 'spa': HTML 미들웨어를 포함하고 SPA 폴백을 사용합니다. 미리보기에서 sirv를 single: true로 구성합니다.
• 'mpa': HTML 미들웨어를 포함합니다.
• 'custom': HTML 미들웨어를 포함하지 마십시오.
• Vite의 SSR 가이드에서 자세히 알아보십시오. 관련 항목: server.middlewareMode.