Vite中commonjsOptions.include的配置与实践指南

1. 理解 commonjsOptions.include 的基本作用

在 Vite 的构建配置中，commonjsOptions 是一个专门用于处理 CommonJS 模块转换的配置项。其中 include 属性扮演着模块过滤器的角色，它决定了哪些模块需要被 Vite 的 CommonJS 转换器处理。默认情况下，Vite 会对所有被检测为 CommonJS 格式的模块进行转换，但在某些特定场景下，我们需要更精确地控制这个转换过程。

1.1 为什么需要显式声明 include

现代前端工程通常混合使用 ESM 和 CommonJS 模块，特别是在以下场景：

• 项目依赖中包含尚未迁移到 ESM 的老旧 npm 包
• 使用了某些仍然采用 CommonJS 发布的流行库
• 项目自身的历史代码中存在 CommonJS 写法

Vite 的默认转换行为在大多数情况下工作良好，但在处理某些特殊模块时可能会出现以下问题：

• 误转换已经符合 ESM 规范的模块
• 对某些特殊格式的模块处理不当
• 需要针对特定模块应用不同的转换规则

这时就需要通过 include 进行精确控制，告诉 Vite："只有这些模块需要特殊处理"。

2. 必须使用 include 的典型场景

2.1 处理非常规 CommonJS 模块

某些 npm 包虽然采用 CommonJS 发布，但其模块导出方式比较特殊。例如：

javascript复制// 某些库可能使用这种非标准导出
const lib = {};
module.exports = function() { /*...*/ };
Object.assign(module.exports, lib);

这种情况下，Vite 可能无法正确识别模块类型，需要在配置中明确指定：

javascript复制// vite.config.js
export default {
  build: {
    commonjsOptions: {
      include: ['special-cjs-package', /node_modules\/unusual-cjs/]
    }
  }
}

2.2 排除转换冲突的模块

当项目中同时存在以下情况时：

1. 使用了基于 ESM 的现代框架（如 Vue 3）
2. 依赖了某些将 ESM 和 CommonJS 混合发布的组件库

这时可能会出现模块系统冲突，典型表现是开发环境正常但生产构建失败。通过 include 精确指定需要转换的模块可以解决这类问题：

javascript复制include: [
  // 明确指定需要转换的 CommonJS 模块
  'lodash',
  'axios',
  /node_modules\/legacy-components/
]

2.3 优化构建性能

对于大型项目，node_modules 中可能包含数百个依赖包。通过 include 缩小转换范围可以显著提升构建速度：

javascript复制include: [
  // 只转换已知的 CommonJS 依赖
  'react',
  'react-dom',
  'moment',
  /node_modules\/cjs-deps/
]

3. include 的高级配置模式

3.1 正则表达式匹配

include 支持正则表达式，可以灵活匹配模块路径：

javascript复制include: [
  // 匹配特定目录下的所有模块
  /node_modules\/legacy\/.