--- url: /config/shared-options.md --- # 共享选项 除非另有说明,本节中的选项适用于所有开发、构建和预览模式。 ## root * **类型:** `string` * **默认值:** `process.cwd()` 项目根目录(即 `index.html` 所在的位置)。可以是绝对路径,也可以是相对于当前工作目录的路径。 请参阅 [项目根目录](/guide/#index-html-and-project-root) 了解更多详情。 ## base * **类型:** `string` * **默认值:** `/` * **相关:** [`server.origin`](/config/server-options.md#server-origin) 开发或生产环境服务的公共基础路径。有效值包括: * 绝对 URL 路径名,例如 `/foo/` * 完整 URL,例如 `https://bar.com/foo/`(开发环境中不会使用源部分,因此值与 `/foo/` 相同) * 空字符串或 `./`(用于嵌入式部署) 请参阅 [公共基础路径](/guide/build#public-base-path) 了解更多详情。 ## mode * **类型:** `string` * **默认值:** serve 时为 `'development'`,build 时为 `'production'` 在配置中指定此项将覆盖 **serve 和 build** 的默认模式。此值也可以通过命令行 `--mode` 选项覆盖。 请参阅 [环境变量和模式](/guide/env-and-mode) 了解更多详情。 ## 输入 * **类型:** `string | string[] | { [entryAlias: string]: string }` 应用程序的入口点,相对于项目根目录解析。当未显式设置 [`build.rolldownOptions.input`](/config/build-options#build-rolldownoptions)、[`build.lib.entry`](/config/build-options#build-lib)、[`build.ssr`](/config/build-options#build-ssr)(如果为 `true`)和 [`optimizeDeps.entries`](/config/dep-optimization-options#optimizedeps-entries) 时,此配置会作为它们的默认值。 当应用程序不使用 `index.html` 入口时,此配置非常有用。这样你只需声明一次入口,而不必在上述选项中重复配置。 ```js twoslash [vite.config.js] import { defineConfig } from 'vite' export default defineConfig({ input: 'src/main.ts', }) ``` ## define * **类型:** `Record` 定义全局常量替换。条目将在开发期间定义为全局变量,并在构建期间静态替换。 Vite 使用 [Oxc 的 define 功能](https://oxc.rs/docs/guide/usage/transformer/global-variable-replacement#define) 来执行替换,因此值表达式必须是包含 JSON 可序列化值(null、boolean、number、string、array 或 object)的字符串,或者是单个标识符。对于非字符串值,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 ``` ::: ## 插件 * **类型:** `(Plugin | Plugin[] | Promise)[]` 要使用的插件数组。假值插件将被忽略,插件数组将被扁平化。如果返回的是 promise,它将在运行前被解析。有关 Vite 插件的更多详细信息,请参阅 [插件 API](/guide/api-plugin)。 ## publicDir * **类型:** `string | false` * **默认值:** `"public"` 用作纯静态资源的目录。此目录中的文件在开发期间服务于 `/`,在构建期间复制到 `outDir` 的根目录,并且总是原样服务或复制而不进行转换。该值可以是绝对文件系统路径或相对于项目根目录的路径。 将 `publicDir` 定义为 `false` 可禁用此功能。 请参阅 [`public` 目录](/guide/assets#the-public-directory) 了解更多详情。 ## cacheDir * **类型:** `string` * **默认值:** `"node_modules/.vite"` 保存缓存文件的目录。此目录中的文件是预捆绑的依赖项或由 vite 生成的其他缓存文件,可以提高性能。你可以使用 `--force` 标志或手动删除该目录来重新生成缓存文件。该值可以是绝对文件系统路径或相对于项目根目录的路径。当未检测到 `package.json` 时,默认为 `.vite`。 ## resolve.alias * **类型:** `Record | Array<{ find: string | RegExp, replacement: string }>` 定义用于替换 `import` 或 `require` 语句中值的别名。这类似于 [`@rollup/plugin-alias`](https://github.com/rollup/plugins/tree/master/packages/alias) 的工作原理。 条目的顺序很重要,首先定义的规则会首先应用。 当别名指向文件系统路径时,始终使用绝对路径。相对别名值将原样使用,不会解析为文件系统路径。 更高级的自定义解析可以通过 [插件](/guide/api-plugin) 实现。 ::: warning 与 SSR 一起使用 如果你为 [SSR 外部化的依赖项](/guide/ssr.md#ssr-externals) 配置了别名,你可能想要别名实际的 `node_modules` 包。[Yarn](https://classic.yarnpkg.com/en/docs/cli/add/#toc-yarn-add-alias) 和 [pnpm](https://pnpm.io/aliases/) 都支持通过 `npm:` 前缀进行别名。 ::: ### 对象格式 (`Record`) 对象格式允许将别名指定为键,将相应的值指定为实际的导入值。例如: ```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` 可以使用 [替换模式](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_string_as_the_replacement),例如 `$1`。例如,要用另一个扩展名替换扩展名,可以使用如下模式: ```js { find:/^(.*)\.js$/, replacement: '$1.alias' } ``` ## resolve.dedupe * **类型:** `string[]` 如果你的应用程序中存在同一依赖项的多个副本(可能是由于提升或 monorepo 中的链接包导致),使用此选项可强制 Vite 始终将列出的依赖项解析为同一个副本(从项目根目录)。 :::warning SSR + ESM 对于 SSR 构建,去重在 `build.rolldownOptions.output` 中配置的 ESM 构建输出上不起作用。一个变通方法是在 ESM 对模块加载具有更好的插件支持之前,使用 CJS 构建输出。 ::: ## resolve.conditions * **类型:** `string[]` * **默认值:** `['module', 'browser', 'development|production']` (`defaultClientConditions`) 解析包的 [条件导出](https://nodejs.org/api/packages.html#packages_conditional_exports) 时允许的其他条件。 具有条件导出的包在其 `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` 条件始终适用。 此外,在解析样式导入时应用 `style` 条件,例如 `@import 'my-library'`。对于某些 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](https://esbuild.github.io/api/#preserve-symlinks)、[webpack#resolve.symlinks ](https://webpack.js.org/configuration/resolve/#resolvesymlinks)。 ## resolve.tsconfigPaths * **类型:** `boolean` * **默认值:** `false` 启用 tsconfig 路径解析功能。`tsconfig.json` 中的 `paths` 选项将用于解析导入。有关更多详细信息,请参阅 [功能](/guide/features.md#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`](#resolve-alias)。 ::: ## html.cspNonce * **类型:** `string` * **相关:** [内容安全策略 (CSP)](/guide/features#content-security-policy-csp) 生成脚本/样式标签时将使用的 nonce 值占位符。设置此值还将生成一个带有 nonce 值的 meta 标签。 ## html.additionalAssetSources * **类型:** `Record` ```ts interface HtmlAssetSource { srcAttributes?: string[] srcsetAttributes?: string[] filter?: (data: { key: string value: string attributes: Record }) => boolean } ``` 定义要视为资源来源的附加 HTML 元素和属性。这扩展了内置列表,内置列表包括标准元素,如 ``、`