Vue Vben Admin 项目中构建时"createRequire"报错分析与解决方案

问题现象

在使用 Vue Vben Admin 5.x 版本进行项目开发时，部分开发者在更新项目依赖后执行构建命令（如 pnpm build）会遇到以下报错信息：

error during build:
../../node_modules/.pnpm/jiti@2.4.2/node_modules/jiti/lib/jiti.mjs (1:9): 
"createRequire" is not exported by "__vite-browser-external", 
imported by "../../node_modules/.pnpm/jiti@2.4.2/node_modules/jiti/lib/jiti.mjs".
file: /node_modules/.pnpm/jiti@2.4.2/node_modules/jiti/lib/jiti.mjs:1:9
1: import { createRequire } from "node:module";

该问题通常出现在以下场景：

1. 向项目的 package.json 中添加了新依赖
2. 执行了 pnpm install 安装依赖
3. 随后执行构建命令时出现报错

问题根源分析

这个错误的核心在于 Node.js 模块系统与 Vite 构建工具之间的兼容性问题。具体来说：

1. createRequire 的作用：这是 Node.js 原生模块提供的方法，用于创建 require 函数实例，常用于模块加载场景。

2. Vite 的浏览器兼容处理：Vite 在构建过程中会将 Node.js 特定的 API 通过 __vite-browser-external 进行替换，以实现浏览器兼容性。

3. jiti 模块的特殊性：jiti 是一个运行时 TypeScript 和 ESM 支持工具，它依赖于 Node.js 的原生模块功能。

4. 依赖安装不完整：当项目采用 monorepo 结构时（如 Vue Vben Admin 的架构），子包和根目录的依赖关系如果没有正确同步，就会导致这类模块解析错误。

解决方案

基础解决方案

1. 完整重装依赖：

   rm -rf node_modules
   pnpm install
   

2. Monorepo 项目的特殊处理： 如果项目采用 monorepo 结构（如 Vue Vben Admin），需要：

   # 在项目根目录执行
   pnpm install
   # 然后进入具体子包目录
   cd packages/your-package
   pnpm run build
   

进阶解决方案

1. 配置 Vite 的优化依赖： 在 vite.config.js 中添加：

   optimizeDeps: {
     include: ['jiti']
   }
   

2. 检查 Node.js 版本兼容性： 确保使用的 Node.js 版本（如 v16+）与项目要求一致。

3. 锁定依赖版本： 在 package.json 中固定 jiti 的版本：

   "resolutions": {
     "jiti": "2.4.2"
   }
   

预防措施

1. 依赖变更后的标准流程：

   • 修改 package.json 后先执行根目录安装
   • 再进入具体工作目录操作

2. 使用一致的包管理器： 整个项目统一使用 pnpm，避免混用 npm 或 yarn。

3. 定期清理缓存：

   pnpm store prune
   

技术原理深入

这个问题的本质是模块系统在构建过程中的转换问题。Vite 作为现代构建工具，采用了原生 ESM 的方式，而 jiti 这样的工具在设计时考虑了 Node.js 的特定环境。当两者在构建过程中产生冲突时，就会导致这类 API 导出错误。

在 monorepo 架构下，这个问题会更加明显，因为：

1. 子包的依赖可能被提升到根目录的 node_modules
2. Vite 的依赖预构建可能没有正确处理这种层级关系
3. pnpm 的严格 node_modules 结构使得模块解析路径更加敏感

理解这些底层原理有助于开发者更好地预防和解决类似问题。