共享选项

root

类型: string
默认: process.cwd()

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

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

base

类型: string
默认: /
相关: server.origin

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

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

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

mode

类型: string
默认: 'development' 用于服务，'production' 用于构建

在配置中指定此选项将覆盖服务和构建的默认模式。此值也可以通过命令行 --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 用户，请确保在 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 构建输出。解决方法是使用 CJS 构建输出，直到 ESM 对模块加载有更好的插件支持。

resolve.conditions

类型: string[]

从包中解析条件导出时允许的附加条件。

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

json

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

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

Vite 有一组“允许的条件”，并将匹配允许列表中的第一个条件。默认允许的条件是：import、module、browser、default 和 production/development，具体取决于当前模式。resolve.conditions 配置选项允许指定其他允许的条件。

解析子路径导出

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

resolve.mainFields

类型: string[]
默认: ['browser', 'module', 'jsnext:main', 'jsnext']

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

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 - 选项。
less - 选项。
styl/stylus - 仅支持 define，可以作为对象传递。

示例

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

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（不创建任何工作线程，并在主线程中运行）

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

css.devSourcemap

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

是否在开发期间启用源映射。

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
默认: false

如果设置为 true，导入的 JSON 将转换为 export default JSON.parse("...")，这比对象字面量性能高得多，尤其是在 JSON 文件很大的情况下。

启用此选项将禁用命名导入。

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
默认值： 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.

共享选项 ​

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 ​