Vite构建报错ERR_REQUIRE_ESM：@rolldown/pluginutils 兼容问题完整解决方案

13次阅读

一、报错完整日志

failed to load config from /home/luomor/git/ezdata/web/vite.config.ts
error during build:
Error [ERR_REQUIRE_ESM]: require() of ES Module /home/luomor/git/ezdata/web/node_modules/@rolldown/pluginutils/dist/index.mjs not supported.
Instead change the require of /home/luomor/git/ezdata/web/node_modules/@rolldown/pluginutils/dist/index.mjs to a dynamic import() which is available in all CommonJS modules.
    at Object.<anonymous> (/home/luomor/git/ezdata/web/node_modules/@vitejs/plugin-vue-jsx/dist/index.cjs:8:21)
    at _require.extensions.<computed> [as .js] (file:///home/luomor/git/ezdata/web/node_modules/vite/dist/node/chunks/dep-Dm0c1Wj2.js:49604:9)
    at Object.<anonymous> (/home/luomor/git/ezdata/web/vite.config.ts:378:37)

二、报错核心根源

1. 本质冲突

Node.js 模块语法强限制：CommonJS(.cjs) 文件禁止使用 require() 导入纯 ESM(.mjs) 模块，仅支持动态 import() 导入。

2. 依赖链路冲突

@vitejs/plugin-vue-jsx 4.x+ 新版内置集成 rolldown 编译工具链；
内置依赖 @rolldown/pluginutils 新版仅打包输出 ESM 格式 index.mjs；
plugin-vue-jsx 本体编译为 CommonJS 格式 index.cjs，内部用 require 加载 mjs，直接触发模块报错。

3. 高发环境

Node.js 16 / 18 低版本LTS（兼容性最差）
Vite4/Vite5 + Vue2/Vue3 混用项目
老旧前端项目、未配置type:module的CommonJS项目

三、分级解决方案（按优先级：最简→适配→改造）

✅ 方案一：降级插件【全网最优、零改代码、推荐首选】

回退无 rolldown 依赖的稳定版 plugin-vue-jsx，彻底规避模块冲突，无需修改vite配置、项目代码。

# npm 执行
npm uninstall @vitejs/plugin-vue-jsx
npm i @vitejs/plugin-vue-jsx@3.1.0 -D

# pnpm 执行
pnpm remove @vitejs/plugin-vue-jsx
pnpm add @vitejs/plugin-vue-jsx@3.1.0 -D

# yarn 执行
yarn remove @vitejs/plugin-vue-jsx
yarn add @vitejs/plugin-vue-jsx@3.1.0 -D

适配：所有Vue2/Vue3、Vite全版本老旧项目，执行完直接重启构建即可修复。

✅ 方案二：锁定依赖版本【保留新版JSX插件专用】

业务必须使用 4.x+ 新版vue-jsx插件，强制锁定低版本兼容rolldown工具包。

安装兼容版工具包

npm i @rolldown/pluginutils@0.0.13 -D

package.json 顶层添加依赖锁定（npm/pnpm生效）

{
  "resolutions": {
    "@rolldown/pluginutils": "0.0.13"
  }
}

重装依赖生效：npm install

✅ 方案三：项目全局改为ESM模式【新项目改造使用】

适配全新前端项目，将项目整体转为ESM模块，消除CJS/ESM导入壁垒，老旧项目慎用，会导致原有require代码报错。

根目录package.json新增顶层配置

{
  "type": "module"
}

改造vite.config.ts语法
1. 所有 require() 改为 import
2. 所有 module.exports 改为 export default
重启本地开发/构建命令

✅ 方案四：修改配置动态导入【临时兜底，不长期使用】

定位报错行：vite.config.ts 第378行，改造静态导入为Node支持的动态import，配置改为异步导出。

// 原有报错代码（CJS静态导入）
const xxx = require('@rolldown/pluginutils')

// 修改后代码（动态ESM导入）
const { xxx } = await import('@rolldown/pluginutils')

// 整文件改为异步配置导出
export default async defineConfig({
  // 原有全部vite配置不变
})

四、通用兜底清理步骤（修改后仍报错执行）

清除依赖、缓存、锁文件，彻底重置依赖环境，解决依赖残留兼容问题

# Linux/Mac 一键清理
rm -rf node_modules package-lock.json .vite-cache

# Windows cmd 执行
rd /s /q node_modules
del package-lock.json

# 重装依赖
npm cache clean --force
npm install