共享配置选项

vite-main配置参考

共享配置选项

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

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 选项覆盖。

更多细节请参阅环境变量与模式。

input

类型： string | string[] | { [entryAlias: string]: string }

应用程序的入口点，相对于项目根目录进行解析。当 build.rolldownOptions.input、build.lib.entry、build.ssr（如果为 true）和 optimizeDeps.entries 未显式设置时，此选项将作为它们的默认值。

当你的应用不使用 index.html 作为入口时，此选项非常有用，只需声明一次入口，无需在上述选项中重复配置。

js twoslash [vite.config.js] 复制代码

import { defineConfig } from 'vite'

export default defineConfig({
  input: 'src/main.ts',
})

define

类型： Record<string, any>

定义全局常量替换。在开发环境中这些条目将被定义为全局变量，在构建时将被静态替换。

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

示例：

js 复制代码

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

::: tip 注意
对于 TypeScript 用户，请确保在 vite-env.d.ts 文件中添加类型声明，以获得类型检查和智能提示。

示例：

ts 复制代码

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

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

条目的顺序很重要，先定义的规则会优先生效。

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

更高级的自定义解析可以通过插件实现。 warning 与 SSR 一起使用
如果你已经为 SSR 外部化依赖配置了别名，可能需要为实际的 node_modules 包设置别名。Yarn 和 pnpm 都支持通过 npm: 前缀设置别名。

对象格式（Record<string, string>）

对象格式允许将别名指定为键，将实际导入值指定为对应的值。例如：
js 复制代码
resolve: {
  alias: {
    utils: '../../../utils',
    'batman-1.0.0': './joker-1.5.0'
  }
}
数组格式（Array<{ find: string | RegExp, replacement: string }>）

数组格式允许将别名指定为对象，这对于复杂的键/值对非常有用。
js 复制代码
resolve: {
  alias: [
    { find: 'utils', replacement: '../../../utils' },
    { find: 'batman-1.0.0', replacement: './joker-1.5.0' },
  ]
}
当 find 是正则表达式时，replacement 可以使用替换模式，例如 $1。例如，要移除扩展名或替换为另一个扩展名，可以使用类似以下的模式：
js 复制代码
{ find:/^(.*)\.js$/, replacement: '$1.alias' }
resolve.dedupe

类型： string[]

如果你的应用中有相同依赖的重复副本（通常是由于 monorepo 中的提升或链接包导致），可以使用此选项强制 Vite 始终将列出的依赖解析为同一副本（从项目根目录）。warning SSR + ESM
对于 SSR 构建，去重对通过 build.rolldownOptions.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 条件始终会被应用。

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

resolve.mainFields

类型： 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

类型： boolean

默认值： false

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

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

resolve.tsconfigPaths

类型： boolean

默认值： false

启用 tsconfig paths 解析功能。tsconfig.json 中的 paths 选项将用于解析导入。更多细节请参阅功能。

paths 仅适用于通过 files 或 include 匹配到 tsconfig.json 的文件。非 JS 扩展名的文件应明确列出，因为单独的 "src" 或 "**/*" include 仅匹配 TS/JS 扩展名，这与 TypeScript 的行为一致。例如，要在 CSS 文件中使用 paths 别名（如 @import '@/foo.css'），请在 files 中列出这些文件，或在 include 中添加明确的扩展名：
json [tsconfig.json] 复制代码
{
  "include": ["src", "src/**/*.css", "src/**/*.scss"]
}
``` warning 不支持 Less

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

html.cspNonce

类型： string

相关： 内容安全策略（CSP）

一个 nonce 值占位符，用于生成 script / style 标签时使用。设置此值还会生成一个带有 nonce 值的 meta 标签。

html.additionalAssetSources

类型： Record<string, HtmlAssetSource>
ts 复制代码
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 Component 或引用资源的非标准属性（如 data-*）时，此选项非常有用。

示例：
js 复制代码
export default defineConfig({
  html: {
    additionalAssetSources: {
      // 自定义 Web Component
      '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
类型：
ts 复制代码
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 modules 行为。这些选项会传递给 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，可以作为对象传入。

示例：
js 复制代码
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 }))

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

示例：
js 复制代码
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `$injectedColor: orange;`,
      },
    },
  },
})
``` tip 导入文件

由于相同的代码会被前置到不同目录的文件中，相对路径将无法正确解析。请使用绝对路径或别名。

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 了解更多信息。 info 重复的 @import
请注意，postcss（postcss-import）在处理重复的 @import 时与浏览器有不同的行为。参见 postcss/postcss-import#462。

css.lightningcss

实验性： 提供反馈

类型：
js 复制代码
import type {
  CSSModulesConfig,
  Drafts,
  Features,
  NonStandard,
  PseudoClasses,
  Targets,
} from 'lightningcss'
js 复制代码
{
  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：
js 复制代码
export default defineConfig({
  oxc: {
    jsx: {
      runtime: 'classic',
      pragma: 'h',
      pragmaFrag: 'Fragment',
    },
  },
})
默认情况下，Oxc 的转换应用于 ts、jsx 和 tsx 文件。你可以通过 oxc.include 和 oxc.exclude 自定义此项，它们可以是正则表达式、picomatch 模式，或两者的数组。

此外，你还可以使用 oxc.jsxInject 为每个由 Oxc 转换的文件自动注入 JSX 辅助导入：
js 复制代码
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' 插件以不同方式处理该资源类型，则可以覆盖此行为）。

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

示例：
js 复制代码
export default defineConfig({
  assetsInclude: ['**/*.gltf'],
})
logLevel

类型： 'info' | 'warn' | 'error' | 'silent'

调整控制台输出的详细程度。默认为 'info'。

customLogger
类型：
ts 复制代码
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
}
使用自定义 logger 来记录消息。你可以使用 Vite 的 createLogger API 获取默认 logger 并对其进行自定义，例如更改消息或过滤掉某些警告。
ts twoslash 复制代码
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 暴露给你的客户端源码。warning 安全说明
envPrefix 不应设置为 ''，这将暴露你的所有环境变量，并导致敏感信息意外泄露。当 Vite 检测到 '' 时会抛出错误。

如果你想要暴露一个不带前缀的变量，可以使用 define 来暴露它：

js 复制代码

define: {
  'import.meta.env.ENV_VARIABLE': JSON.stringify(process.env.ENV_VARIABLE)
}

:::

appType

类型： 'spa' | 'mpa' | 'custom'
默认值： 'spa'

你的应用程序是单页应用（SPA）、多页应用（MPA）还是自定义应用（SSR 和具有自定义 HTML 处理的框架）：

'spa'：包含 HTML 中间件并使用 SPA 回退。在预览中配置 sirv 时使用 single: true
'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

input

define

plugins

publicDir

cacheDir

resolve.alias

对象格式（Record<string, string>）

数组格式（Array<{ find: string | RegExp, replacement: string }>）

resolve.dedupe

resolve.conditions

resolve.mainFields

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

帮助我们改进文档

对象格式（`Record<string, string>`）

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