共享选项

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

root

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

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

详情请参阅 项目根目录。

base

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

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

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

详情请参阅 公共基础路径。

mode

• 类型： string
• 默认值： 服务启动时为 'development'，构建时为 'production'

在配置中指定此项将覆盖服务启动和构建的默认模式。此值也可以通过命令行 --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

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 }>

定义用于在 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.rollupOptions.output 配置的 ESM 构建输出无效。一个变通方法是使用 CJS 构建输出，直到 ESM 对模块加载拥有更好的插件支持。

resolve.conditions 不继承

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

解析来自包的 条件导出 时允许使用的额外条件。

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

{
  "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 条件始终会被应用。

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

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

resolve.tsconfigPaths

• 类型： boolean
• 默认值： false

启用 tsconfig 路径解析功能。tsconfig.json 中的 paths 选项将被用于解析导入。详情请参阅 特性。

html.cspNonce

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

生成 script / style 标签时使用的 nonce 值占位符。设置此值还将生成一个带有 nonce 值的元标签 (meta tag)。

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 时，此选项无效。如果已启用 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 将不会创建任何工作线程，而是在主线程中运行预处理器。

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

css.devSourcemap

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

是否在开发阶段启用 sourcemaps。

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 Transformer 的选项。最常见的使用场景是自定义 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) => {
  // 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)，还是自定义应用（SSR 和具有自定义 HTML 处理的框架）。

• 'spa'：包含 HTML 中间件并使用 SPA 回退。在预览模式下，通过 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 的下一个主要版本做好准备。列表可能会随着新特性的开发随时进行更新、添加或删除。

有关可能选项的详细信息，请参阅 破坏性变更 页面。