用途:面向 Vite 开发环境的依赖预构建(pre-bundling)配置与排错,覆盖依赖优化、缓存失效和 monorepo 场景。
主要能力:
- 解释预构建存在的原因:将 CJS/UMD 转为 ESM,并合并模块减少 HTTP 请求。预构建仅在开发模式生效,生产构建使用 Rolldown(v8+)或 Rollup(v5-v7)。
- 区分版本工具:v5/v6/v7 使用 esbuild,配置键为 optimizeDeps.esbuildOptions;v8+ 使用 Rolldown,键为 optimizeDeps.rolldownOptions。
- 提供 include/exclude 决策规则:CJS/UMD 依赖绝不可 exclude;纯 ESM 且内部模块很多的依赖(如 lodash-es)建议 include 以提升性能;链接的 monorepo 包若不导出 ESM,必须加入 optimizeDeps.include。
- 自动发现机制:Vite 从 HTML 入口或 optimizeDeps.entries 开始爬取,识别裸导入并预打包到 node_modules/.vite;插件转换代码、变量路径动态导入、不可达文件中的导入会漏掉,需手动 include。
- 缓存失效:lockfile、patches 目录、vite.config.js 相关字段、NODE_ENV 变化会触发重新打包;预构建产物带强缓存头与版本查询串。强制重置可用 vite --force、optimizeDeps.force: true 或删除 node_modules/.vite。
- 排错指引:启动慢、浏览器模块未找到或 CJS 报错、编辑 node_modules 后代码过期、CJS 默认导出互操作问题(可用 optimizeDeps.needsInterop)。
使用方式:在 vite.config.js 中配置 optimizeDeps.include、exclude、entries、noDiscovery、force 等;修改 node_modules 后需加 --force。noDiscovery: true 时必须列出所有依赖,否则裸导入解析失败。
适用场景:SPA 重依赖项目、monorepo 链接包、需要手动控制发现入口的项目。
限制:预构建仅用于开发环境;资料未提供具体价格、平台等信息。