Vue3项目Webpack迁Vite：require is not defined报错全解析与三把钥匙

Vue3 项目从 Webpack 迁到 Vite 之后很多人第一次撞上的报错就是控制台里那句冷冰冰的require is not defined。这个报错特别有迷惑性代码在旧项目里跑得好好的换到 Vite 就原地爆炸而且报错位置往往指向某个第三方库或者一段看起来毫无问题的老代码。我前后帮几个团队处理过这类迁移问题发现绝大多数人第一反应是去搜怎么在 Vite 里用 require然后被一堆半截方案带偏最后要么装了个插件了事但没搞懂原理要么干脆把整个构建链回退。这篇就把这个问题的来龙去脉拆干净给你三把真正能通关的钥匙顺带把每把钥匙背后的取舍逻辑讲透让你下次再遇到类似的环境差异问题能自己判断。1. 先搞清楚 require 在 Vite 里为什么直接失效1.1 两种模块体系的根本分歧要理解这个报错得先明白require到底是什么。它是 CommonJS 规范里的模块加载函数运行在 Node.js 环境里本质是一个在模块执行时由宿主注入的全局函数。Webpack 时代之所以能到处写require是因为 Webpack 自己实现了一套模块运行时它在打包阶段把require调用静态分析并替换成了内部函数浏览器里跑的其实是 Webpack 注入的兼容层而不是真正的 Noderequire。Vite 走的是另一条路。开发阶段它依赖浏览器原生的 ES Module 能力通过script typemodule直接加载源码浏览器只认import压根不认识require这个标识符。生产构建阶段 Vite 用的是 RollupRollup 的模块处理同样以 ESM 为核心。所以当你的代码里出现require(...)浏览器执行到那一行时会在作用域链里找require找不到就抛出ReferenceError: require is not defined。这不是 Vite 的 bug而是两种模块体系在运行时层面的硬性差异。这里有个容易被忽略的点报错不一定来自你自己的代码。很多时候是你引入的某个依赖它的入口文件是 CommonJS 格式里面大量使用require。Vite 在预构建依赖预打包阶段会用 esbuild 把 CommonJS 转成 ESM大部分情况下能处理掉但如果这个依赖被排除在预构建之外或者它内部有动态require表达式转换就会失败报错就冒出来了。1.2 报错出现的三类典型场景我把实际遇到的案例归了归类基本逃不出这三种场景类型典型表现根因业务代码残留老代码里写了const path require(path)迁移时没改干净浏览器环境无此函数第三方依赖报错堆栈指向node_modules/xxx依赖是 CJS 格式且未被正确预构建动态加载require(someVariable)变量拼接路径静态分析无法确定模块转换失效第一类最好办属于自己挖的坑自己填。第二类最烦因为报错位置在依赖内部你改不了源码。第三类最隐蔽因为它在开发环境可能不报错一到生产构建才炸。分清楚自己属于哪一类后面的处理才有方向别一上来就无脑装插件。1.3 为什么不能简单粗暴地补一个 require网上流传最广的方案是装个vite-plugin-require-transform之类的插件或者在index.html里塞一段脚本手动定义window.require。这类做法在特定场景下能跑通但我不建议作为首选原因有两个。其一手动定义require只是让标识符不报错它并没有真正实现模块解析逻辑遇到需要实际加载模块的场景照样歇菜。其二插件转换依赖静态分析对动态require无能为力而且会增加构建复杂度出问题时排查成本更高。正确的思路应该是先判断这个require是必须保留还是可以消除。绝大多数业务代码里的require都可以直接改成import这是最干净的做法。只有当依赖内部无法修改时才需要考虑兼容层方案。这个判断顺序很重要搞反了就会陷入为了兼容而兼容的泥潭。2. 第一把钥匙把业务代码里的 require 彻底 ESM 化2.1 静态 require 的等价改写先看最常见的静态引入。老代码里经常这么写const fs require(fs) const path require(path) const _ require(lodash)在 Vite 项目里只要这些模块是给浏览器用的直接改成 ESM 语法即可import fs from fs import path from path import _ from lodash看起来简单但有几个细节要注意。fs和path是 Node 内置模块浏览器里根本没有如果你在纯前端代码里引入它们改完import之后会变成另一个报错——模块找不到。这种情况说明这段代码本来就不该跑在浏览器里要么它属于构建脚本应该放到vite.config.js或独立的 Node 脚本里要么它需要换成浏览器可用的替代方案。比如path的路径拼接在前端可以用模板字符串或URL对象替代fs的文件读取则应该改成通过接口请求。对于lodash这类同时提供 CJS 和 ESM 版本的库改成import后 Vite 会自动走 ESM 入口还能享受 tree-shaking。如果你只需要其中几个函数更推荐按需引入import debounce from lodash/debounce import cloneDeep from lodash/cloneDeep这样打包体积能小一大截算是迁移过程中的意外收获。2.2 条件加载与动态 require 的替代写法真正麻烦的是动态require。比如这种按条件加载模块的写法if (env production) { config require(./config.prod.js) } else { config require(./config.dev.js) }这种代码在 Webpack 里能跑因为 Webpack 会把两个分支都打包进去。到了 Viterequire直接报错。正确的 ESM 写法是用动态import()if (env production) { config (await import(./config.prod.js)).default } else { config (await import(./config.dev.js)).default }注意import()返回的是 Promise所以外层函数得是async或者用.then()处理。另外动态导入的路径如果是变量拼接Vite 需要能静态分析出可能的模块范围否则会警告。比如import(./locales/ lang .js)这种Vite 会尝试把./locales/目录下所有文件都纳入候选建议用import.meta.glob来显式声明const modules import.meta.glob(./locales/*.js) const loadLocale (lang) modules[./locales/${lang}.js]()import.meta.glob是 Vite 提供的批量导入能力返回一个路径到加载函数的映射既保留了动态性又让构建工具能提前知道有哪些模块这是处理动态 require最正统的姿势。2.3 迁移时的批量排查技巧一个中型项目里require可能散落在几十个文件里手动一个个找效率太低。我的做法是先用正则全局搜一遍grep -rn require( src/ --include*.js --include*.vue --include*.ts把结果按文件归类然后分三批处理第一批是纯静态引入直接机械替换成import第二批是条件加载改成动态import()第三批是引用了 Node 内置模块的单独拎出来判断归属。处理完再跑一次构建看报错是否收敛。这里有个实操心得替换的时候别用 IDE 的一键全局替换因为require在字符串里、注释里也可能出现无脑替换会误伤。我一般会先看 grep 结果确认每一处的上下文再动手。另外改完之后记得检查package.json里的type字段如果项目里还有.js文件用 CJS 语法可能需要把这类文件后缀改成.cjs避免 ESM 解析冲突。3. 第二把钥匙让第三方 CJS 依赖被正确预构建3.1 依赖预构建到底做了什么业务代码改干净了报错还在堆栈指向node_modules里某个包这就进入第二类场景。Vite 的依赖预构建机制本来就是为了解决这个问题它在启动时用 esbuild 扫描node_modules把 CommonJS 格式的依赖转成 ESM缓存到node_modules/.vite/deps目录浏览器加载的就是转换后的版本。大部分主流库都能被自动处理但有几类会漏网。一是被你在optimizeDeps.exclude里手动排除的依赖二是通过import引入但 Vite 没识别到的深层路径三是依赖内部用了 esbuild 无法静态转换的动态require。判断方法很简单看报错堆栈里的文件路径如果指向.vite/deps下的文件说明预构建已经介入但转换不完整如果直接指向node_modules/xxx/dist/index.js这种原始路径说明这个依赖压根没被预构建。3.2 手动纳入预构建的配置方式确认是预构建遗漏后在vite.config.js里显式声明export default defineConfig({ optimizeDeps: { include: [some-cjs-package, another-package/deep-path] } })include数组里的模块会被强制纳入预构建。这里有个坑包名要写准确深层路径也要写全比如import some-package/lib/utils这种光写some-package可能不够得把完整路径也列进去。改完配置后记得删掉node_modules/.vite缓存目录再重启否则 Vite 可能复用旧缓存你会以为配置没生效。还有一种情况是依赖本身提供了 ESM 版本但package.json的exports字段配置有问题导致 Vite 解析到了 CJS 入口。这时候可以尝试在resolve.alias里手动指向 ESM 文件resolve: { alias: { some-package: some-package/dist/index.esm.js } }不过这种做法属于打补丁依赖升级后路径可能变得记在项目的迁移文档里方便后续维护。3.3 预构建仍失败时的兜底方案有些依赖确实顽固esbuild 转换不了比如内部有require加变量拼接、或者依赖了 Node 的process、Buffer等全局对象。这时候有两个兜底方向。第一个方向是换库。如果这个依赖只是提供了某个小功能找一个纯 ESM 的替代品往往比折腾兼容层更省事。我在一个项目里遇到过某个日期处理库的旧版本死活转不了换成另一个轻量库之后问题直接消失代码还少了几百行。第二个方向是用rollup/plugin-commonjs在生产构建阶段兜底。Vite 的build.rollupOptions可以挂 Rollup 插件import commonjs from rollup/plugin-commonjs export default defineConfig({ build: { rollupOptions: { plugins: [commonjs()] } } })注意这个插件主要作用于生产构建开发阶段的预构建还是走 esbuild所以它解决不了vite dev时的报错。如果你的问题只在vite build时出现这个方案很对症如果开发时也报错还得回到预构建配置上想办法。4. 第三把钥匙用兼容层处理无法改造的遗留模块4.1 什么情况下才该上兼容层前两把钥匙能解决九成以上的场景剩下那一成通常是依赖是公司内部的老包短期没法改或者某个模块必须在运行时动态加载且加载逻辑依赖require的同步特性。这种时候才轮到兼容层出场。我要强调一点兼容层是最后手段不是首选。因为它本质上是在 ESM 环境里模拟 CJS 的运行时会增加包体积、拖慢启动而且行为边界需要仔细验证。上之前先问自己三个问题这个依赖能不能换能不能让维护方发一个 ESM 版本能不能把用到它的代码隔离到一个懒加载的 chunk 里三个都否了再考虑兼容层。4.2 基于插件注入的兼容实现社区里有几种思路我比较推荐的是在构建阶段做转换而不是在运行时打补丁。以vite-plugin-commonjs这类插件为例它会在转换阶段识别require调用并改写为import。配置大致如下import commonjs from vite-plugin-commonjs export default defineConfig({ plugins: [commonjs()] })这类插件的原理是遍历 AST找到require调用节点替换成对应的导入语句。它对静态require效果好对动态require依然无能为力。所以用之前先用前面说的 grep 方法确认一下你的遗留模块里到底是静态还是动态调用别指望一个插件包治百病。如果只是想让标识符不报错、且模块本身已经通过其他方式加载好了可以在入口文件顶部做一次轻量定义if (typeof window.require undefined) { window.require (id) { throw new Error(require(${id}) 未被支持请改用 import) } }这段代码的作用不是真的实现加载而是把未定义的报错换成一条更清晰的提示方便定位问题。我在排查阶段经常用这招因为它能让报错信息直接告诉你哪个模块在调用require比浏览器默认的堆栈直观。4.3 兼容层的验证清单上了兼容层之后别急着宣布搞定按这个清单过一遍开发环境vite dev启动无报错页面功能正常生产构建vite build成功产物里没有残留的require调用预览vite preview下功能与开发环境一致被兼容的模块在懒加载、条件加载场景下都能正常工作打包体积增量在可接受范围内对比加兼容层前后的dist大小我见过有人只验证了开发环境就上线结果生产构建时 Rollup 报错因为开发和生产走的是两套转换链路。这个清单看着琐碎但能帮你避开这类环境差异坑。5. 排查这类问题的通用思路与经验沉淀5.1 从报错堆栈反推问题归属遇到require is not defined第一件事不是搜方案而是读堆栈。堆栈最上面那一帧告诉你报错发生在哪个文件。如果是src/下的业务文件走第一把钥匙如果是node_modules/下的依赖走第二把钥匙如果堆栈里出现了.vite/deps路径说明预构建参与了但没转干净重点查optimizeDeps配置。这个判断流程能帮你省掉大量试错时间。另外注意报错发生的时机。是页面一加载就报还是点了某个按钮才报前者通常是入口链路上的静态引入后者多半是动态加载或懒加载模块。时机信息能进一步缩小排查范围。5.2 环境差异类问题的迁移心法require报错只是 Webpack 迁 Vite 过程中环境差异的一个缩影。类似的还有process.env在浏览器里未定义、__dirname不可用、global对象缺失等等。这些问题的共同点是它们都依赖 Node 或打包器注入的运行时环境而 Vite 的开发模式更贴近浏览器原生。我的经验是迁移时先把项目里所有依赖打包器魔法的写法列个清单包括require、process.env、__dirname、module.exports、动态require、require.context。然后逐个对照 Vite 的替代方案process.env换成import.meta.envrequire.context换成import.meta.globmodule.exports换成export。提前做这张对照表比遇到一个查一个效率高得多。5.3 几个容易反复踩的小坑最后分享几个我在实操中反复见到的细节问题。第一改完代码后 Vite 的 HMR 有时不会重新预构建依赖导致你以为改动没生效其实需要手动删node_modules/.vite再重启。第二optimizeDeps.include里写的包名如果和实际import的路径不一致预构建不会触发比如你 import 的是some-package/es/index.js但 include 里只写了some-package这种情况要把完整子路径也加上。第三monorepo 项目里本地包如果没配好exports字段Vite 可能解析到 CJS 入口需要在根配置里统一处理。提示每次调整optimizeDeps或resolve.alias之后养成删缓存重启的习惯能避免大量配置明明改了却没反应的假象。这套排查思路我在几个不同规模的项目上都验证过从几十个文件的小项目到上百个依赖的中型应用基本都能按业务代码 ESM 化 → 依赖预构建 → 兼容层兜底的顺序收敛问题。真正花时间的往往不是改代码而是判断每一处require该走哪条路这个判断力只能靠多踩几次坑慢慢积累。