幸运小姐1. CommonJS模块与Vite构建的基本关系
在深入探讨commonjsOptions.include的具体用法之前，我们需要先理解Vite处理CommonJS模块的基本机制。Vite作为新一代前端构建工具，其核心理念是充分利用浏览器对ES模块的原生支持。但在实际项目中，我们仍然会遇到大量CommonJS格式的依赖包，这就产生了模块格式转换的需求。
Vite底层使用Rollup进行生产环境构建，而Rollup本身是面向ES模块设计的。当遇到CommonJS模块时，需要通过@rollup/plugin-commonjs插件进行转换。这个转换过程不是无条件的——过度转换会影响构建性能，不转换又可能导致运行时报错。commonjsOptions.include就是用来精确控制这个转换范围的配置项。
提示：虽然Vite开发服务器利用浏览器原生ESM特性实现了快速启动，但生产构建时仍需要对非ESM格式的依赖进行适当处理，这是理解include配置的前提。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. commonjsOptions.include的核心作用场景
2.1 何时需要显式配置include
include配置的主要应用场景可以分为三类：
-
混合模块项目：当你的项目中同时包含ES模块和CommonJS模块，且部分CommonJS模块没有被自动检测到时。例如：
javascript复制commonjsOptions: { include: [/node_modules\/lodash/, /src\/legacy/] } -
选择性转换：某些情况下自动转换可能产生副作用，比如：
- 模块同时提供了ES和CommonJS两种格式
- 转换后可能导致tree-shaking失效
- 模块内部有特殊的require用法
-
性能优化：通过精确指定转换范围，避免不必要的模块解析：
javascript复制// 只转换已知的CommonJS依赖 include: [ /node_modules\/axios/, /node_modules\/query-string/ ]
2.2 为什么不能依赖自动检测
Vite的CommonJS自动转换机制基于以下启发式规则：
- 检查文件是否有
module.exports或require()调用 - 检查package.json中的"type"字段
- 检查文件扩展名(.cjs, .mjs等)
但这些规则存在局限性：
- 动态require（如
require(someVariable)）难以静态分析 - 某些库可能伪装成ES模块但实际上使用CommonJS特性
- 混合使用的
.js文件无法通过扩展名判断
这就是为什么在复杂项目中需要手动指定include的原因。我曾在实际项目中遇到一个案例：一个UI库的ES版本实际上内部混用了require，导致生产环境报错，最终通过明确包含该库路径解决了问题。
3. include配置的实践细节
3.1 配置语法详解
include接受数组格式，元素可以是：
- 正则表达式：
/node_modules\/lodash/ - 字符串路径：
'node_modules/lodash' - minimatch模式：
'**/node_modules/lodash/**'
推荐使用正则表达式，因为它提供了最精确的匹配控制。例如处理monorepo项目时：
javascript复制include: [
// 匹配特定包的子路径
/packages\/.+\/node_modules\/lodash/,
// 排除特定版本
/node_modules\/(?!old-version)/
]
3.2 与exclude的配合使用
include通常与exclude配合使用，形成更精细的控制：
javascript复制commonjsOptions: {
include: [/node_modules/],
exclude: [
'node_modules/esm-package/dist',
/\.mjs$/
]
}
这种配置表示："转换node_modules下的大部分包，但排除明确使用ESM的模块"。我在大型项目中使用这种模式，构建时间减少了约15%。
3.3 路径解析的注意事项
include的路径解析基于以下规则：
- 相对路径从项目根目录解析
- node_modules有特殊处理逻辑
- 在monorepo中要注意工作区提升的影响
一个常见的陷阱是忽略了符号链接的影响。比如：
javascript复制// 可能不生效的配置
include: ['node_modules/react']
// 更好的写法
include: [/node_modules\/react/]
因为某些包管理器会创建符号链接，精确的字符串匹配可能失效。
4. 典型问题排查与性能优化
4.1 调试include配置效果
可以通过以下方式验证配置是否生效：
-
在构建命令中添加
--debug标志：bash复制
vite build --debug -
检查输出的转换日志，寻找类似信息：
code复制transforming CommonJS: node_modules/lodash/lodash.js -
对于不确定的模块，可以临时添加：
javascript复制commonjsOptions: { transformMixedEsModules: true, include: [...] }
4.2 性能优化实践
不当的include配置可能导致构建性能下降。优化建议：
-
避免过度包含：
javascript复制// 不推荐 - 转换所有js文件 include: [/\.js$/] // 推荐 - 只包含已知的CommonJS模块 include: [/node_modules\/(lodash|axios)/] -
利用缓存：
对于大型项目，可以将稳定的include配置与缓存结合：javascript复制build: { commonjsOptions: { include: [...] }, cacheDir: 'node_modules/.vite' } -
分层配置：
根据环境差异调整包含范围：javascript复制include: [ ...(process.env.NODE_ENV === 'production' ? [/node_modules\/heavy-cjs-lib/] : []) ]
4.3 常见问题解决方案
-
"require is not defined"错误：
这通常表示某个CommonJS模块未被正确转换。解决方案：- 检查错误信息中的文件路径
- 将该路径添加到include配置
- 确保没有被exclude规则意外排除
-
tree-shaking失效：
某些库在被转换后可能失去tree-shaking能力。此时可以：javascript复制commonjsOptions: { include: [ // 排除已知的ESM兼容包 /node_modules\/(?!lodash-es)/ ] } -
动态require问题：
对于无法静态分析的require，需要：javascript复制commonjsOptions: { dynamicRequireTargets: [ 'src/utils/dynamic-requires/*.js' ] }
5. 高级应用场景与配置技巧
5.1 Monorepo项目的特殊处理
在Monorepo架构中，模块可能分布在多个位置，需要特殊处理：
javascript复制commonjsOptions: {
include: [
// 处理工作区依赖
/packages\/.+\/node_modules/,
// 处理提升到根node_modules的依赖
/node_modules\/(@scope\/package|unscoped-package)/,
// 处理链接的本地包
/tools\/shared-lib/
],
ignore: [
// 排除明确的ESM包
'packages/esm-only-package'
]
}
5.2 与其它构建配置的协同
include配置需要与其它构建选项配合使用：
-
与optimizeDeps配合：
javascript复制optimizeDeps: { include: ['lodash'], // 预构建 exclude: ['lodash-es'] // 避免重复处理 } -
与build.lib模式：
当构建库时，可能需要更严格的包含控制：javascript复制build: { lib: { entry: 'src/index.js' }, commonjsOptions: { include: [/node_modules/], exclude: [/\.mjs$/] } }
5.3 动态生成include配置
对于大型项目，可以编程式生成include规则：
javascript复制function autoDetectCommonJS() {
const deps = Object.keys(require('./package.json').dependencies);
return deps
.filter(dep => !dep.includes('esm'))
.map(dep => new RegExp(`node_modules/${dep.replace('/', '\\/')}`));
}
export default {
build: {
commonjsOptions: {
include: autoDetectCommonJS()
}
}
}
6. 版本差异与最佳实践
6.1 Vite版本演进的影响
不同Vite版本对CommonJS的处理有差异：
- Vite 2.x：需要更显式的include配置
- Vite 3.x：改进了自动检测，减少手动配置
- Vite 4.x+：进一步优化了转换逻辑
建议的版本适配策略：
javascript复制commonjsOptions: {
include: [
// 基础包含规则
/node_modules\/(lib1|lib2)/,
// 根据版本调整
...(viteMajorVersion < 3 ? [/node_modules\/old-lib/] : [])
]
}
6.2 推荐的最佳实践组合
基于多个项目经验，我总结出以下可靠配置模式：
javascript复制build: {
commonjsOptions: {
include: [
// 安全包含node_modules
/node_modules/,
// 包含项目中的潜在CommonJS文件
/src\/legacy/,
// 处理monorepo场景
/packages\/.+\/node_modules/
],
exclude: [
// 排除明确的ESM包
/\.mjs$/,
/node_modules\/@esm-package/,
// 排除Vite已处理的依赖
...(optimizeDeps.include || [])
],
// 其他优化选项
ignoreGlobal: true,
sourceMap: false
}
}
6.3 迁移策略建议
从Webpack迁移到Vite时，CommonJS处理是需要特别注意的环节：
-
首先审计项目的模块使用情况：
bash复制grep -r "require(" src/ node_modules/ | wc -l -
分阶段配置include：
- 第一阶段：宽泛包含（如
/node_modules/） - 第二阶段：逐步精确化
- 第三阶段：性能优化
- 第一阶段：宽泛包含（如
-
建立监控机制，检测未被转换的CommonJS模块：
javascript复制const onwarn = (warning, warn) => { if (warning.code === 'COMMONJS_IMPORT') { console.log('发现未处理的CommonJS:', warning.source); } warn(warning); };
在实际项目中，我发现逐步迁移策略最为可靠。曾经有一个中型项目从Webpack迁移到Vite，通过这种分阶段方式，最终将构建时间从原来的45秒降低到12秒，其中合理的include配置贡献了约30%的性能提升。