Vite项目中CommonJS转换配置与优化实践

1. 为什么需要关注 CommonJS 转换问题

在 Vite 项目中处理 CommonJS 模块是个看似简单实则容易踩坑的话题。作为从 Webpack 迁移到 Vite 的老手，我深刻体会到这个配置项的重要性。现代前端工具链正在全面转向 ESM，但现实情况是我们仍需要与大量 CommonJS 模块共存。

Vite 的构建流程基于 Rollup，而 Rollup 原生只支持 ES Modules。这就意味着所有使用 require() 和 module.exports 的代码都需要被转换。@rollup/plugin-commonjs 就是这个转换器，而 build.commonjsOptions.include 就是控制它工作范围的关键开关。

2. 必须配置 include 的三种典型场景

2.1 处理非 node_modules 中的遗留代码

我最近接手的一个老项目就遇到了这个问题。项目中有个 lib/ 目录存放着五年前写的工具函数，全部使用 CommonJS 规范。当用 Vite 构建时，控制台不断报错 module.exports is not defined。

解决方案：

javascript复制// vite.config.js
export default defineConfig({
  build: {
    commonjsOptions: {
      include: [
        /lib\/.*\.js$/,
        // 也可以明确指定文件路径
        path.resolve(__dirname, 'lib/legacy-utils.js')
      ]
    }
  }
})

经验之谈：对于老项目迁移，建议先用 /** @type {import('vite').UserConfig} */ 注释来获取类型提示，避免配置错误。

2.2 处理 node_modules 中的问题依赖包

上周在集成一个日期处理库时就踩了坑。这个库的 package.json 同时声明了 module 和 main 字段，但实际导出方式很诡异。构建后运行时出现 `formatDate is not a functio