共享选项

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

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 使用 esbuild defines 执行替换，因此值表达式必须是包含 JSON 可序列化值（null、布尔值、数字、字符串、数组或对象）的字符串或单个标识符。对于非字符串值，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 文件中添加类型声明，以获取类型检查和 Intellisense。

示例

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

plugins

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

要使用的插件数组。Falsy 插件将被忽略，插件数组将被扁平化。如果返回 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 option 传递给 @rollup/plugin-alias。可以是对象，也可以是 { find, replacement, customResolver } 对的数组。

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

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

与 SSR 一起使用

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

resolve.dedupe

类型： string[]

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

SSR + ESM

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

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 值的 meta 标签。

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
- 如果已安装，则使用 sass-embedded，否则使用 sass。为了获得最佳性能，建议安装 sass-embedded 包。
- 选项
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: {
        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
默认： 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 repo 中找到。

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' 插件以不同方式处理资产类型，则可以覆盖此字符串）。

内置的资产类型列表可以在此处找到。

示例

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 | 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) 还是自定义应用程序（具有自定义 HTML 处理的 SSR 和框架）

'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 ​