依赖优化选项

• 相关链接： 依赖预打包

除非另有说明，本节中的选项仅适用于依赖优化器，该优化器仅在开发环境中使用。

optimizeDeps.entries

• 类型： string | string[]

默认情况下，Vite 会扫描你所有的 .html 文件以检测需要预打包的依赖（忽略 node_modules、build.outDir、__tests__ 和 coverage）。如果指定了顶层 input 或 build.rolldownOptions.input，Vite 将改为扫描这些入口点。

如果这些方式都不符合你的需求，你可以使用此选项指定自定义入口——该值应为相对于 Vite 项目根目录的 tinyglobby 模式 或模式数组。这将覆盖默认的入口推断。当显式定义 optimizeDeps.entries 时，默认仅忽略 node_modules 和 build.outDir 文件夹。如果需要忽略其他文件夹，可以在条目列表中使用以 ! 开头的忽略模式。对于显式包含字符串 node_modules 的模式，node_modules 将不会被忽略。

optimizeDeps.exclude

• 类型： string[]

要从预打包中排除的依赖项。

:::warning 关于 CommonJS
不应将 CommonJS 依赖项从优化中排除。如果一个 ESM 依赖项被排除在优化之外，但它嵌套了 CommonJS 依赖项，则应将 CommonJS 依赖项添加到 optimizeDeps.include 中。示例：

import { defineConfig } from 'vite'
// ---cut---
export default defineConfig({
  optimizeDeps: {
    include: ['esm-dep > cjs-dep'],
  },
})

optimizeDeps.include

• 类型： string[]

默认情况下，不在 node_modules 内的链接包不会被预打包。使用此选项可强制预打包链接包。

实验性功能： 如果你使用的库有许多深层导入，你还可以指定尾部通配符模式以一次性预打包所有深层导入。这样可以避免在使用新的深层导入时不断重新预打包。提供反馈。例如：

js twoslash 复制代码

import { defineConfig } from 'vite'
// ---cut---
export default defineConfig({
  optimizeDeps: {
    include: ['my-lib/components/**/*.vue'],
  },
})

optimizeDeps.rolldownOptions

• 类型： Omit<RolldownOptions, 'input' | 'logLevel' | 'output'> & { output?: Omit<RolldownOutputOptions, 'format' | 'sourcemap' | 'dir' | 'banner'> }

传递给 Rolldown 在依赖扫描和优化期间使用的选项。

某些选项被省略，因为更改它们将与 Vite 的依赖优化不兼容。

• plugins 会与 Vite 的依赖插件合并

optimizeDeps.esbuildOptions

• 类型： Omit<EsbuildBuildOptions, 'bundle' | 'entryPoints' | 'external' | 'write' | 'watch' | 'outdir' | 'outfile' | 'outbase' | 'outExtension' | 'metafile'>
• 已弃用

此选项在内部被转换为 optimizeDeps.rolldownOptions。请使用 optimizeDeps.rolldownOptions 替代。

optimizeDeps.force

• 类型： boolean

设置为 true 以强制进行依赖预打包，忽略先前缓存的优化依赖。

optimizeDeps.noDiscovery

• 类型： boolean
• 默认值： false

当设置为 true 时，自动依赖发现将被禁用，只有 optimizeDeps.include 中列出的依赖会被优化。在开发期间，仅支持 CJS 的依赖必须存在于 optimizeDeps.include 中。

optimizeDeps.holdUntilCrawlEnd

• 实验性功能： 提供反馈
• 类型： boolean
• 默认值： true

启用后，在冷启动时，它将保持首次优化依赖的结果，直到所有静态导入被扫描完毕。这避免了当发现新依赖并触发生成新的公共块时，需要进行整页重新加载。如果所有依赖都能被扫描器以及 include 中显式定义的依赖找到，则最好禁用此选项，以让浏览器并行处理更多请求。

optimizeDeps.disabled

• 已弃用
• 实验性功能： 提供反馈
• 类型： boolean | 'build' | 'dev'
• 默认值： 'build'

此选项已被弃用。自 Vite 5.1 起，构建期间的依赖预打包已被移除。将 optimizeDeps.disabled 设置为 true 或 'dev' 会禁用优化器，而设置为 false 或 'build' 则会在开发期间保持优化器启用。

要完全禁用优化器，请使用 optimizeDeps.noDiscovery: true 来禁止自动发现依赖，并保持 optimizeDeps.include 未定义或为空。warning
构建期间的依赖优化是一项实验性功能。尝试此策略的项目还通过 build.commonjsOptions: { include: [] } 移除了 @rollup/plugin-commonjs。如果你这样做了，会有警告引导你重新启用它以在打包时支持仅 CJS 的包。
:::

optimizeDeps.needsInterop

• 实验性功能
• 类型： string[]

强制在导入这些依赖时使用 ESM interop。Vite 能够正确检测依赖何时需要 interop，因此通常不需要此选项。然而，不同的依赖组合可能会导致其中一些依赖以不同方式预打包。将这些包添加到 needsInterop 可以通过避免整页重新加载来加速冷启动。如果你的某个依赖出现这种情况，你会收到一条警告，建议你在配置中将包名添加到此数组中。