共享选项

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

root

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

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

有关更多详细信息，请参阅项目根目录。

base

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

在开发或生产环境中提供服务时的基本公共路径。有效值包括

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

有关更多详细信息，请参阅公共基本路径。

mode

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

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

有关更多详细信息，请参阅环境变量和模式。

define

类型： Record<string, any>

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

Vite 使用 esbuild define 执行替换，因此值表达式必须是包含 JSON 可序列化值的字符串（null、布尔值、数字、字符串、数组或对象）或单个标识符。对于非字符串值，Vite 会自动使用 JSON.stringify 将其转换为字符串。

示例

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

注意

对于 TypeScript 用户，请确保在 env.d.ts 或 vite-env.d.ts 文件中添加类型声明以获取类型检查和 IntelliSense。

示例

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

plugins

类型： (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, customResolver?: ResolverFunction | ResolverObject }>

将作为其 entries 选项传递给 @rollup/plugin-alias。可以是对象，也可以是 { find, replacement, customResolver } 对的数组。

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

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

与 SSR 结合使用

如果您已为 SSR 外部依赖项配置了别名，则可能需要为实际的 node_modules 包指定别名。 Yarn 和 pnpm 都支持通过 npm: 前缀指定别名。

resolve.dedupe

类型： string[]

如果您的应用程序中存在相同依赖项的重复副本（可能是由于提升或单仓中链接的包导致的），请使用此选项强制 Vite 始终将列出的依赖项解析到同一副本（来自项目根目录）。

SSR + ESM

对于 SSR 构建，重复数据删除不适用于从 build.rollupOptions.output 配置的 ESM 构建输出。解决方法是在 ESM 对模块加载具有更好的插件支持之前使用 CJS 构建输出。

resolve.conditions

类型： 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 条件。

解析子路径导出

以“/”结尾的导出键已弃用，并且可能无法正常工作。请联系包作者改用 * 子路径模式。

resolve.mainFields

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

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

resolve.extensions

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

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

resolve.preserveSymlinks

类型： boolean
默认值： false

启用此设置会导致 vite 通过原始文件路径（即不跟随符号链接的路径）而不是真实文件路径（即跟随符号链接后的路径）来确定文件标识。

相关： esbuild#preserve-symlinks、webpack#resolve.symlinks

html.cspNonce

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

生成脚本/样式标签时将使用的 nonce 值占位符。设置此值还会生成一个包含 nonce 值的元标记。

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
  /**
   * default: 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

类型： Record<string, object>

指定传递给 CSS 预处理器的选项。文件扩展名用作选项的键。每个预处理器的支持选项可以在其各自的文档中找到。

sass/scss
- 使用 api: "modern-compiler" | "modern" | "legacy" 选择要使用的 Sass API（如果安装了 sass-embedded，则默认为 "modern-compiler"，否则为 "modern"）。为了获得最佳性能，建议使用 sass-embedded 包配合 api: "modern-compiler"。"legacy" API 已弃用，将在 Vite 7 中删除。
- 选项（现代）
- 选项（传统）.
less: 选项。
styl/stylus: 仅支持 define，可以作为对象传递。

示例

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

css.preprocessorOptions[extension].additionalData

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

此选项可用于为每个样式内容注入额外的代码。请注意，如果您包含实际的样式而非仅包含变量，则这些样式将在最终捆绑包中重复。

示例

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

css.preprocessorMaxWorkers

实验性： 提供反馈
类型： number | true
默认值： 0（不创建任何 worker 并在主线程中运行）

如果设置了此选项，则 CSS 预处理器将在可能的情况下在 worker 中运行。true 表示 CPU 数量减 1。

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 时才会进行字符串化。

esbuild

类型： ESBuildOptions | false

ESBuildOptions 扩展了 esbuild 自身的转换选项。最常见的用例是自定义 JSX。

export default defineConfig({
  esbuild: {
    jsxFactory: 'h',
    jsxFragment: 'Fragment',
  },
})

默认情况下，esbuild 应用于 ts、jsx 和 tsx 文件。您可以使用 esbuild.include 和 esbuild.exclude 自定义此行为，它们可以是正则表达式、picomatch 模式或它们的数组。

此外，您还可以使用 esbuild.jsxInject 为 esbuild 转换的每个文件自动注入 JSX 帮助器导入。

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

当 build.minify 为 true 时，默认情况下会应用所有最小化优化。要禁用某些方面的最小化，请将 esbuild.minifyIdentifiers、esbuild.minifySyntax 或 esbuild.minifyWhitespace 选项中的任何一个设置为 false。请注意，esbuild.minify 选项不能用于覆盖 build.minify。

设置为 false 以禁用 esbuild 转换。

assetsInclude

类型： string | RegExp | (string | RegExp)[]
相关： 静态资产处理

指定其他 picomatch 模式作为静态资产处理，以便

当从 HTML 中引用或通过 fetch 或 XHR 直接请求时，它们将从插件转换管道中排除。
从 JS 中导入它们将返回其解析后的 URL 字符串（如果您有一个 enforce: 'pre' 插件以不同方式处理资产类型，则可以覆盖此行为）。

内置的资产类型列表可以在这里找到 here。

示例

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
) => {
  // Ignore empty CSS files warning
  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
默认值： root

加载 .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 回退。在预览中使用 single: true 配置 sirv
'mpa': 包含 HTML 中间件
'custom': 不包含 HTML 中间件

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

future

类型： Record<string, 'warn' | undefined>
相关： 重大更改

启用未来的重大更改，以便为顺利迁移到下一版本的 Vite 做好准备。随着新功能的开发，此列表可能会随时更新、添加或删除。

有关可能的选项的详细信息，请参阅重大更改页面。

共享选项 ​

root ​

base ​

mode ​

define ​

plugins ​

publicDir ​

cacheDir ​

resolve.alias ​

resolve.dedupe ​

resolve.conditions ​

resolve.mainFields ​

resolve.extensions ​

resolve.preserveSymlinks ​

html.cspNonce ​

css.modules ​

css.postcss ​

css.preprocessorOptions ​

css.preprocessorOptions[extension].additionalData ​

css.preprocessorMaxWorkers ​

css.devSourcemap ​

css.transformer ​

css.lightningcss ​

json.namedExports ​

json.stringify ​

esbuild ​

assetsInclude ​

logLevel ​

customLogger ​

clearScreen ​

envDir ​

envPrefix ​

appType ​

future ​