vite中动态导入模块需显式配置optimizedeps.include以预构建，包括第三方深层路径模块、字符串拼接路径、ui库子模块及未静态引用的工具模块；路径须完全一致且不支持glob。
在 Vite 中，动态导入（import()）的模块默认不会被自动加入依赖预构建（optimizeDeps）列表，这会导致开发启动时首次加载这些模块慢、HMR 失效，甚至出现“module not found”或运行时解析失败等问题。通过配置 optimizeDeps.include 显式声明需要预构建的动态依赖，能确保它们被提前编译为 ESM 并缓存，从而提升热更新稳定性和首屏加载体验。
哪些动态导入模块需要加到 include 中？
主要指以下几类未被 Vite 静态分析捕获、但实际运行时会用到的模块：
- 第三方库中未导出默认对象、仅通过命名导出或深层路径引入的模块（如
lodash-es/cloneDeep、date-fns/format） - 使用字符串拼接或变量拼接的动态路径（如
import(`./locales/${lang}.js`)中的固定 locale 文件） - 按需加载的 UI 组件库子模块（如
ant-design-vue/es/button） - 自定义工具函数或配置模块，被
import()异步加载且未在任何静态import中出现过
如何正确配置 optimizeDeps.include
在 vite.config.ts（或 .js）的 optimizeDeps 选项中，将模块路径以字符串形式写入 include 数组。路径必须与你代码中 import() 内部的字符串**完全一致**（包括后缀）：
export default defineConfig({
optimizeDeps: {
include: [
'lodash-es/cloneDeep',
'date-fns/format',
'ant-design-vue/es/button',
'./utils/async-routes.js', // 注意：相对路径需以 ./ 开头，且是相对于项目根目录
'vue-i18n/dist/vue-i18n.runtime.esm-bundler.js'
]
}
})
⚠️ 注意：include 中的路径不支持 glob 模式（如 './locales/*.js'），也不支持正则；若需批量包含，可用脚本生成数组，或配合 exclude + 更宽泛的 entries 策略。
验证是否生效的实用方法
配置后可通过以下方式确认模块已被预构建：
- 启动开发服务器（
vite dev），观察控制台输出中Pre-bundling dependencies日志，确认目标模块出现在列表中 - 检查
node_modules/.vite目录下是否存在对应模块的缓存文件（如lodash-es_cloneDeep.js） - 在浏览器开发者工具的 Network 面板中，刷新页面并触发动态导入，确认该模块请求返回的是
200且来自/@modules/...路径（说明走的是预构建代理） - 修改被 include 的模块源码，观察 HMR 是否正常触发动态模块更新（若没加 include，常出现 HMR 不生效或报错）
进阶技巧：配合 optimizeDeps.exclude 和 entries 使用
当 include 的模块本身有副作用或依赖特殊插件处理时，可搭配 exclude 避免重复处理；对入口级动态模块（如路由组件），更推荐用 entries 显式声明：
optimizeDeps: {
include: ['lodash-es/cloneDeep'],
exclude: ['some-lib/broken-esm'],
entries: ['./src/router/routes.ts'] // 让 Vite 扫描该文件内所有 import()，自动收集依赖
}
这样既能覆盖动态导入场景，又避免手动维护长列表，适合中大型项目。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
