共享选项

除非另有说明，本节中的选项适用于所有开发、构建和预览模式。

root

类型： string
默认值： process.cwd()

项目根目录（即 index.html 所在的位置）。可以是绝对路径，也可以是相对于当前工作目录的路径。

请参阅项目根目录了解更多详情。

base

类型： string
默认值： /
相关： server.origin

开发或生产环境服务的公共基础路径。有效值包括：

绝对 URL 路径名，例如 /foo/
完整 URL，例如 https://bar.com/foo/（开发环境中不会使用源部分，因此值与 /foo/ 相同）
空字符串或 ./（用于嵌入式部署）

请参阅公共基础路径了解更多详情。

mode

类型： string
默认值： serve 时为 'development'，build 时为 'production'

在配置中指定此项将覆盖 serve 和 build 的默认模式。此值也可以通过命令行 --mode 选项覆盖。

请参阅环境变量和模式了解更多详情。

define

类型： Record<string, any>

定义全局常量替换。条目将在开发期间定义为全局变量，并在构建期间静态替换。

Vite 使用 Oxc 的 define 功能来执行替换，因此值表达式必须是包含 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 用户，请确保在 vite-env.d.ts 文件中添加类型声明以获得类型检查和智能感知。

示例：

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

插件

类型： (Plugin | Plugin[] | Promise<Plugin | Plugin[]>)[]

要使用的插件数组。假值插件将被忽略，插件数组将被扁平化。如果返回的是 promise，它将在运行前被解析。有关 Vite 插件的更多详细信息，请参阅插件 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 }>

定义用于替换 import 或 require 语句中值的别名。这类似于 @rollup/plugin-alias 的工作原理。

条目的顺序很重要，首先定义的规则会首先应用。

当别名指向文件系统路径时，始终使用绝对路径。相对别名值将原样使用，不会解析为文件系统路径。

更高级的自定义解析可以通过插件实现。

与 SSR 一起使用

如果你为 SSR 外部化的依赖项配置了别名，你可能想要别名实际的 node_modules 包。Yarn 和 pnpm 都支持通过 npm: 前缀进行别名。

对象格式 (`Record<string, string>`)

对象格式允许将别名指定为键，将相应的值指定为实际的导入值。例如：

resolve: {
  alias: {
    utils: '../../../utils',
    'batman-1.0.0': './joker-1.5.0'
  }
}

数组格式 (`Array<{ find: string | RegExp, replacement: string }>`)

数组格式允许将别名指定为对象，这对于复杂的键/值对很有用。

resolve: {
  alias: [
    { find: 'utils', replacement: '../../../utils' },
    { find: 'batman-1.0.0', replacement: './joker-1.5.0' },
  ]
}

当 find 是正则表达式时，replacement 可以使用替换模式，例如 $1。例如，要用另一个扩展名替换扩展名，可以使用如下模式：

{ find:/^(.*)\.js$/, replacement: '$1.alias' }

resolve.dedupe

类型： string[]

如果你的应用程序中存在同一依赖项的多个副本（可能是由于提升或 monorepo 中的链接包导致），使用此选项可强制 Vite 始终将列出的依赖项解析为同一个副本（从项目根目录）。

SSR + ESM

对于 SSR 构建，去重在 build.rolldownOptions.output 中配置的 ESM 构建输出上不起作用。一个变通方法是在 ESM 对模块加载具有更好的插件支持之前，使用 CJS 构建输出。

resolve.conditions non-inherit

类型： string[]
默认值： ['module', 'browser', 'development|production'] (defaultClientConditions)

解析包的条件导出时允许的其他条件。

具有条件导出的包在其 package.json 中可能具有以下 exports 字段：

json

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

这里，import 和 require 是“条件”。条件可以嵌套，并且应从最具体到最不具体指定。

development|production 是一个特殊值，根据 process.env.NODE_ENV 的值替换为 production 或 development。当 process.env.NODE_ENV === 'production' 时替换为 production，否则替换为 development。

注意，如果满足要求，import、require、default 条件始终适用。

此外，在解析样式导入时应用 style 条件，例如 @import 'my-library'。对于某些 CSS 预处理器，也会应用它们对应的条件，即 Sass 的 sass 和 Less 的 less。

resolve.mainFields non-inherit

类型： string[]
默认值： ['browser', 'module', 'jsnext:main', 'jsnext'] (defaultClientMainFields)

解析包的入口点时要尝试的 package.json 中的字段列表。注意，这比从 exports 字段解析的条件导出优先级低：如果从 exports 成功解析了入口点，则将忽略主字段。

resolve.extensions

类型： string[]
默认值： ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']

尝试导入省略扩展名时的文件扩展名列表。注意，不建议为自定义导入类型（例如 .vue）省略扩展名，因为它会干扰 IDE 和类型支持。

resolve.preserveSymlinks

Type: boolean
Default: false

Enabling this option will cause vite to determine file identity using the original file path (that is, the path without following symlinks) rather than the real file path (that is, the path after following symlinks).

Related: esbuild#preserve-symlinks, webpack#resolve.symlinks

resolve.tsconfigPaths

类型： boolean
默认值： false

启用 tsconfig 路径解析功能。tsconfig.json 中的 paths 选项将用于解析导入。有关更多详细信息，请参阅功能。

paths 仅适用于通过 files 或 include 被 tsconfig.json 匹配到的文件。非 JS 扩展名文件应显式列在其中，因为仅写 "src" 或 "**/*" 的 include 只会匹配 TS/JS 扩展名，这与 TypeScript 的行为一致。例如，要在 CSS 文件中使用 paths 别名（例如 @import '@/foo.css'），请将这些文件列入 files，或为 include 添加显式扩展名：

tsconfig.json

json

{
  "include": ["src", "src/**/*.css", "src/**/*.scss"]
}

不支持 Less

resolve.tsconfigPaths 不适用于 .less 文件内部。Less 只会将导入文件的目录传给 Vite，而不会传递文件本身，因此 Vite 无法找到与之匹配的 tsconfig.json。请在 Less 中的 @import 使用相对路径或 resolve.alias。

html.cspNonce

类型： string
相关： 内容安全策略 (CSP)

生成脚本/样式标签时将使用的 nonce 值占位符。设置此值还将生成一个带有 nonce 值的 meta 标签。

html.additionalAssetSources

类型： Record<string, HtmlAssetSource>

interface HtmlAssetSource {
  srcAttributes?: string[]
  srcsetAttributes?: string[]
  filter?: (data: {
    key: string
    value: string
    attributes: Record<string, string>
  }) => boolean
}

定义要视为资源来源的附加 HTML 元素和属性。这扩展了内置列表，内置列表包括标准元素，如 <img src>、<video src>、<link href> 等。

当使用自定义 Web 组件或引用资源的非标准属性（如 data-*）时，这会很有用。

示例：

export default defineConfig({
  html: {
    additionalAssetSources: {
      // 自定义 Web 组件
      'html-import': { srcAttributes: ['src'] },
      // 为现有元素添加 data-* 属性
      img: { srcAttributes: ['data-src-dark', 'data-src-light'] },
      // 使用 srcset 格式
      'my-picture': { srcsetAttributes: ['data-srcset'] },
      // 使用过滤函数
      'my-component': {
        srcAttributes: ['asset'],
        filter: ({ attributes }) => attributes.type === 'image',
      },
    },
  },
})

css.modules

类型：

interface CSSModulesOptions {
  getJSON?: (
    cssFileName: string,
    json: Record<string, string>,
    outputFileName: string,
  ) => void
  scopeBehaviour?: 'global' | 'local'
  globalModulePaths?: RegExp[]
  exportGlobals?: boolean
  generateScopedName?:
    | string
    | ((name: string, filename: string, css: string) => string)
  hashPrefix?: string
  /**
   * 默认值：undefined
   */
  localsConvention?:
    | 'camelCase'
    | 'camelCaseOnly'
    | 'dashes'
    | 'dashesOnly'
    | ((
        originalClassName: string,
        generatedClassName: string,
        inputFile: string,
      ) => string)
}

配置 CSS 模块行为。选项会传递给 postcss-modules。

使用 Lightning CSS 时，此选项没有任何效果。如果启用，应改用 css.lightningcss.cssModules。

css.postcss

类型： string | (postcss.ProcessOptions & { plugins?: postcss.AcceptedPlugin[] })

内联 PostCSS 配置，或用于搜索 PostCSS 配置的自定义目录（默认为项目根目录）。

对于内联 PostCSS 配置，它需要与 postcss.config.js 相同的格式。但对于 plugins 属性，只能使用数组格式。

搜索由 postcss-load-config 完成，并且只会加载受支持的配置文件名。默认情况下，不会搜索工作区根目录（如果未找到工作区，则为项目根目录）之外的配置文件。如果需要，你可以指定根目录之外的自定义路径来加载特定的配置文件。

注意，如果提供了内联配置，Vite 将不会搜索其他 PostCSS 配置源。

css.preprocessorOptions

Type: Record<string, object>

Specify options to pass to CSS preprocessors. The file extension will be used as the key for the options. Supported options for each preprocessor can be found in their respective documentation:

sass/scss:
- If sass-embedded is installed, it will be used; otherwise, sass will be used. For best performance, it is recommended to install the sass-embedded package.
- Options
less: Options.
styl/stylus: Only define is supported, and it can be passed as an object.

Example:

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

css.preprocessorOptions[extension].additionalData

Type: string | ((source: string, filename: string) => (string | { content: string; map?: SourceMap }))

This option can be used to inject extra code into each style content. Note that if actual styles are included instead of just variables, these styles will be duplicated in the final bundle.

Example:

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

Importing Files

Since the same code will be prepended to files in different directories, relative paths cannot be resolved correctly. Please use absolute paths or aliases.

css.preprocessorMaxWorkers

类型： number | true
默认值： true

指定 CSS 预处理器可以使用的最大线程数。true 表示最多为 CPU 数量减 1。当设置为 0 时，Vite 不会创建任何 worker，并会在主线程中运行预处理器。

根据预处理器选项，即使此选项未设置为 0，Vite 也可能在主线程上运行预处理器。

css.devSourcemap

实验性： 提供反馈
类型： boolean
默认值： false

是否在开发期间启用 sourcemap。

css.transformer

实验性： 提供反馈
类型： 'postcss' | 'lightningcss'
默认值： 'postcss'

选择用于 CSS 处理的引擎。查看更多信息请参见 Lightning CSS。

重复的 @import

请注意，postcss（postcss-import）对重复 @import 的处理行为与浏览器不同。参见 postcss/postcss-import#462。

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,
  // ...
}

配置 Lightning CSS。完整的转换选项可以在 Lightning CSS 仓库中找到。

json.namedExports

类型： boolean
默认值： true

是否支持从 .json 文件进行命名导入。

json.stringify

类型： boolean | 'auto'
默认值： 'auto'

如果设置为 true，导入的 JSON 将被转换为 export default JSON.parse("...")，这比对象字面量性能显著更高，尤其是当 JSON 文件很大时。

如果设置为 'auto'，仅当数据大于 10kB 时才会将数据字符串化。

oxc

类型： OxcOptions | false

OxcOptions 扩展自 Oxc 转换器的选项。最常见的用例是自定义 JSX：

export default defineConfig({
  oxc: {
    jsx: {
      runtime: 'classic',
      pragma: 'h',
      pragmaFrag: 'Fragment',
    },
  },
})

默认情况下，Oxc 转换应用于 ts、jsx 和 tsx 文件。你可以使用 oxc.include 和 oxc.exclude 自定义此项，它们可以是正则表达式、picomatch 模式，或两者的数组。

此外，你还可以使用 oxc.jsxInject 为每个被 Oxc 转换的文件自动注入 JSX 辅助导入：

export default defineConfig({
  oxc: {
    jsxInject: `import React from 'react'`,
  },
})

设置为 false 以禁用 Oxc 转换。

esbuild

类型： ESBuildOptions | false
已弃用

此选项在内部转换为 oxc 选项。请改用 oxc 选项。

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

设置为 false 以防止 Vite 在记录某些消息时清除终端屏幕。通过命令行，使用 --clearScreen false。

envDir

类型： string | false
默认值： root

加载 .env 文件的目录。可以是绝对路径，也可以是相对于项目根目录的路径。false 将禁用 .env 文件加载。

有关环境文件的更多信息，请参阅这里。

envPrefix

类型： string | string[]
默认值： VITE_

以 envPrefix 开头的环境变量将通过 import.meta.env 暴露给你的客户端源代码。

安全说明

envPrefix 不应设置为 ''，这将暴露所有环境变量并导致敏感信息意外泄露。当检测到 '' 时 Vite 将抛出错误。

如果你想暴露一个无前缀的变量，你可以使用 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 回退。在 preview 中使用 single: true 配置 sirv
'mpa': 包含 HTML 中间件
'custom': 不包含 HTML 中间件

在 Vite 的 SSR 指南中了解更多。相关：server.middlewareMode。

devtools

实验性： 提供反馈
类型： boolean | DevToolsConfig
默认值： false

启用 devtools 集成以可视化内部状态和构建分析。确保 @vitejs/devtools 已作为依赖安装。此功能目前仅在构建模式下支持。

详见 Vite DevTools。

future

类型： Record<string, 'warn' | undefined>
相关： 破坏性变更

启用未来的破坏性变更，以便为平滑迁移到 Vite 的下一个主要版本做好准备。随着新功能的开发，列表可能会随时更新、添加或移除。

请参阅破坏性变更页面以了解可能选项的详细信息。

共享选项 ​

root ​

base ​

mode ​

define ​

插件 ​

publicDir ​

cacheDir ​

resolve.alias ​

对象格式 (Record<string, string>) ​

数组格式 (Array<{ find: string | RegExp, replacement: string }>) ​

resolve.dedupe ​

resolve.conditions non-inherit ​

resolve.mainFields non-inherit ​

resolve.extensions ​

resolve.preserveSymlinks ​

resolve.tsconfigPaths ​

html.cspNonce ​

html.additionalAssetSources ​

css.modules ​

css.postcss ​

css.preprocessorOptions ​

css.preprocessorOptions[extension].additionalData ​

css.preprocessorMaxWorkers ​

css.devSourcemap ​

css.transformer ​

css.lightningcss ​

json.namedExports ​

json.stringify ​

oxc ​

esbuild ​

assetsInclude ​

logLevel ​

customLogger ​

clearScreen ​

envDir ​

envPrefix ​

appType ​

devtools ​

future ​

共享选项

root

base

mode

define

插件

publicDir

cacheDir

resolve.alias

对象格式 (`Record<string, string>`)

数组格式 (`Array<{ find: string | RegExp, replacement: string }>`)

resolve.dedupe

resolve.conditions non-inherit

resolve.mainFields non-inherit

resolve.extensions

resolve.preserveSymlinks

resolve.tsconfigPaths

html.cspNonce

html.additionalAssetSources

css.modules

css.postcss

css.preprocessorOptions

css.preprocessorOptions[extension].additionalData

css.preprocessorMaxWorkers

css.devSourcemap

css.transformer

css.lightningcss

json.namedExports

json.stringify

oxc

esbuild

assetsInclude

logLevel

customLogger

clearScreen

envDir

envPrefix

appType

devtools

future