Vite构建时CJS弃用警告的解决方案

问题描述

在Vite 5中使用vite build命令进行项目构建时，控制台会出现以下警告提示：

The CJS build of Vite's Node API is deprecated. See https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details.

该警告表明Vite已弃用CommonJS(CJS)格式的Node API，默认转向ES Modules(ESM)规范。官方文档提供了VITE_CJS_TRACE=true标志来调试问题来源，但直接在脚本中使用可能引发错误：

# Windows错误示例
VITE_CJS_TRACE=true vite build
'VITE_CJS_TRACE' is not recognized as an internal or external command

核心问题

Vite 5+版本已全面转向ESM规范，但项目中存在CJS模块引用会导致此警告。需迁移至ESM或正确配置环境变量。

永久解决方案

方法一：配置文件扩展名更改

将现有配置文件扩展名改为ESM格式：

• JavaScript项目
  vite.config.js → vite.config.mjs

• TypeScript项目
  vite.config.ts → vite.config.mts

原理

.mjs/.mts后缀明确指示Node.js使用ESM模块系统

方法二：package.json 配置修改

在项目根目录的package.json中添加模块类型声明：

{
  "name": "your-project",
  "version": "1.0.0",
  "type": "module", // 添加此配置
  "scripts": {
    "build": "vite build"
  }
}

临时调试方案

定位被弃用的CJS引用

在不同操作系统下设置环境变量：

Windows(PowerShell)

# package.json配置
"build": "set \"VITE_CJS_TRACE=true\" && vite build"

Linux/macOS

# package.json配置
"build": "VITE_CJS_TRACE=true vite build"

执行后将显示详细栈追踪，帮助定位引发警告的具体模块：

Deprecated CJS usage detected at:
  - node_modules/some-package/dist/cjs-module.js:15:20
  - file:///project/src/main.js:5:10

解决方案对比

方法	适用场景	优点	注意事项
配置文件.mjs/.mts	Vite独立项目	显式声明模块系统	需要重命名文件
"type":"module"	全项目ESM迁移	统一项目模块规范	需确保所有文件支持ESM
VITE_CJS_TRACE调试	定位问题依赖	快速识别问题模块	不建议作为最终解决方案

不推荐解决方案

某些答案建议修改开发服务器端口(如server: { port: 3001 })：此操作与警告无关，不会解决CJS弃用问题。

迁移ESM最佳实践

1. 检查依赖兼容性

   npm ls | grep cjs # 检查cjs依赖

2. 分批迁移
   逐步将项目中的.js文件重命名为.mjs，或添加package.json配置

3. 更新Vite相关插件
   确保所有Vite插件已更新到支持ESM的版本

4. 验证构建

   rm -rf node_modules/.vite # 清除缓存
   npm run build            # 重新构建

参考资源

• Vite官方迁移指南
• Node.js ESM文档
• CommonJS vs ES Modules详解