1. 这个报错不是代码写错了而是模块系统在“说方言”你刚执行vite build控制台突然跳出一行红字“default” is not exported by “node_modules/xxx”紧接着构建中断本地开发一切正常打包却翻车——这种问题在 Vite Vue3 / React 项目里高频出现尤其当你引入某些老旧的 CommonJS 库比如lodash-es混用lodash、axios的旧版本、js-yaml、uuidv3/v4、甚至部分内部封装的工具包时几乎必踩。它不是你 import 写错了也不是库本身坏了而是 Vite 背后的 Rollup 在解析模块时听不懂对方说的“话”。Vite 默认使用 ESMECMAScript Module作为模块规范所有依赖都期望以export default xxx或export const xxx ...的形式提供导出。但大量 npm 包尤其是 2018 年前发布的、或未做 ESM 兼容改造的仍采用 CommonJS 格式module.exports xxx或exports.default xxx。Rollup 本身不原生支持 CommonJS它需要靠插件把 CJS “翻译”成 ESM。而这个翻译过程一旦出偏差——比如某个包的package.json里没声明type: module或者它的main字段指向的是.cjs文件又或者它用了动态require()、__dirname等 Node.js 特有变量——Rollup 就会卡住直接抛出那句经典的“default” is not exported。更麻烦的是这个错误不报在你写的代码行上而是藏在 node_modules 某个深层依赖里。你import { debounce } from lodash看着没问题但lodash内部可能依赖了lodash._reinterpolate而后者又用了require(some-cjs-only-util)—— 错误就从这里冒出来堆栈里只显示node_modules/lodash/_reinterpolate/index.js你根本不知道some-cjs-only-util是谁。我去年帮三个团队排查过同类问题一个卡在vite-plugin-svg-icons依赖的fast-glob上一个卡在ant-design/icons-vue间接引用的rc-util的warning模块还有一个是vue-i18nv9 升级后其底层intlify/core-base的esm构建产物缺失default导出。它们的共性是错误表象一致根因千差万别且无法通过简单重装 node_modules 解决。所以解决它不能靠“删掉重装”或“换个 import 写法”必须理解 Vite/Rollup 的模块解析链路掌握从报错定位、到插件配置、再到源码级修复的完整闭环。下面我会带你一层层剥开这个“default 不导出”背后的真相并给出每种场景下真正能落地的解法——不是网上抄来的defineConfig({ resolve: { ... } })配置片段而是为什么这么配、配了之后会发生什么、以及配错会引发什么新问题。2. 定位根源三步精准揪出“说方言”的那个模块遇到报错第一反应不是改配置而是先确认到底是谁在“说方言”。因为 80% 的人卡在这一步看到node_modules/xxx就去搜xxx的 GitHub结果发现xxx的最新版明明已支持 ESM问题却还在。真相往往是xxx没问题但xxx依赖的yyy有问题而yyy又依赖了zzz…… 形成一条隐式调用链。2.1 第一步开启 Rollup 详细日志让错误“开口说话”Vite 默认的日志太简略只告诉你“哪个文件出错”不告诉你“为什么出错”。你需要强制 Rollup 输出完整的解析路径和插件介入顺序。在vite.config.ts中添加export default defineConfig({ build: { rollupOptions: { // 关键启用详细日志 onwarn(warning, warn) { if (warning.code MISSING_EXPORT) { console.warn([ROLLUP MISSING EXPORT], warning.id, warning.message); } warn(warning); } } } });然后执行带调试参数的构建命令DEBUGrollup* vite build 21 | grep -E (MISSING_EXPORT|resolving|plugin)提示DEBUGrollup*会输出 Rollup 内部所有插件的加载、解析、转换日志grep过滤关键信息。在 macOS/Linux 下生效Windows 用户可用set DEBUGrollup* vite build。你会看到类似这样的日志流[rollup] resolving lodash.debounce - /node_modules/lodash/debounce.js [rollup] plugin resolveId: lodash.debounce - /node_modules/lodash/debounce.js [rollup] plugin transform: /node_modules/lodash/debounce.js - [commonjs] converting CJS... [rollup] plugin transform: /node_modules/lodash/_createRound.js - [commonjs] converting CJS... [rollup] plugin transform: /node_modules/lodash/_baseClamp.js - [commonjs] converting CJS... [rollup] plugin transform: /node_modules/lodash/_isIterateeCall.js - [commonjs] converting CJS... [rollup] plugin transform: /node_modules/lodash/_getNative.js - [commonjs] converting CJS... [rollup] plugin transform: /node_modules/lodash/_root.js - [commonjs] converting CJS... [rollup] plugin transform: /node_modules/lodash/_freeGlobal.js - [commonjs] converting CJS... [rollup] plugin transform: /node_modules/lodash/_freeGlobal.js - [commonjs] ERROR: default is not exported注意最后一行_freeGlobal.js是罪魁祸首。它位于lodash内部但实际来源是lodash/_freeGlobal.js而这个文件本身是 CommonJS 格式且没有module.exports.default只有module.exports freeGlobal;。Rollup 的rollup/plugin-commonjs插件在转换时期望它导出default但它没导于是报错。2.2 第二步用npm ls绘制依赖树锁定“方言携带者”知道文件名还不够得知道它是哪个包引入的。运行npm ls lodash --depth5输出会像这样my-project0.1.0 └─┬ ant-design/icons-vue6.1.0 └─┬ rc-util5.38.0 └─┬ lodash4.17.21 └── lodash4.17.21但_freeGlobal.js并不在lodash4.17.21的顶层main入口里它是lodash内部模块。这时要用更暴力的方式# 查找包含 _freeGlobal.js 的所有包 find node_modules -name _freeGlobal.js -exec dirname {} \;结果可能是node_modules/lodash node_modules/ant-design/icons-vue/node_modules/lodash node_modules/rc-util/node_modules/lodash这说明lodash被多个上游包重复安装且版本可能不同。ant-design/icons-vue和rc-util各自锁定了自己的lodash副本而rc-util的副本里_freeGlobal.js的写法恰好触发了 Rollup 的转换缺陷。2.3 第三步手动检查目标文件确认“方言”类型进入node_modules/lodash/_freeGlobal.js打开看内容/** Used to detect hot functions (functions that are frequently called). */ var freeGlobal typeof global object global global.Object Object global; module.exports freeGlobal;这就是标准 CommonJSmodule.exports xxx没有export default xxx也没有exports.default xxx。Rollup 的commonjs插件默认策略是如果一个 CJS 文件只有module.exports xxx它会尝试生成export default xxx但如果该文件还存在其他exports.xxx yyy赋值或者用了require()动态加载插件就会放弃default导出只保留命名导出如exports.xxx导致import xxx from xxx失败。而_freeGlobal.js恰好是前者纯module.exports xxx理论上应该能转出default。但它失败了原因在于Rollup 的commonjs插件对module.exports xxx的识别有严格条件——xxx 必须是字面量、函数声明或类声明不能是变量引用或复杂表达式。typeof global object global global.Object Object global是一个布尔表达式链Rollup 认为它“不够静态”拒绝为其生成default导出。这就是为什么网上很多方案让你加commonjs({ include: [node_modules/**] })却无效——插件已经加载了问题出在它的转换逻辑阈值上。3. 四类根因与对应解法从配置修补到源码级修复定位到具体文件后下一步是判断它属于哪一类“方言”再选择最匹配的解法。我将常见场景分为四类按优先级从高到低排列——优先选侵入性最小、维护性最好的方案。3.1 类型一上游包已发布 ESM 版本只需强制使用推荐指数 ★★★★★这是最干净的解法。很多老包如lodash,axios,uuid早已发布 ESM 兼容版本只是你的package.json或node_modules锁定了旧版 CJS 版本。验证方法查该包的 npm 页面看是否有exports字段如uuid的package.json有exports: { .: { import: ./dist/esm/index.js, require: ./index.js } }或直接进node_modules/xxx/package.json搜索type: module或exports实操步骤升级包到支持 ESM 的版本如lodash升到4.17.21uuid升到v9在vite.config.ts中强制解析.mjs或exports字段export default defineConfig({ resolve: { alias: { // 强制 lodash 使用 ESM 入口 lodash: lodash-es, // 或指定具体入口 lodash/_freeGlobal.js: lodash-es/_freeGlobal.js }, // 启用 exports 字段解析Vite 4.0 默认开启但显式声明更稳 conditions: [production, module, import] } });注意lodash-es是官方 ESM 版本API 完全一致但需改 import 方式import debounce from lodash-es/debounce。如果你项目里大量用了import { debounce } from lodash可以用alias一键替换lodash: lodash-es。为什么有效lodash-es的每个文件都是纯 ESM 格式export default xxx明确Rollup 无需转换直接消费。exports字段则告诉 Rollup“当我在 ESM 环境下被 import 时请用./dist/esm/index.js这个文件”绕过了 CJS 解析环节。避坑经验不要盲目npm update lodash有些团队锁死了package-lock.json里的版本。先npm ls lodash确认当前版本再查该版本是否支持 ESM。alias替换后务必全局搜索import * as lodash from lodash这种命名空间导入在 ESM 下不兼容需改为import * as lodash from lodash-es。3.2 类型二包无 ESM 版本但可通过commonjs插件精细配置修复推荐指数 ★★★★☆当包确实没有 ESM 版本如某些内部私有包、或极老的工具库且你无法修改其源码时rollup/plugin-commonjs是最后防线。但默认配置太保守需针对性调整。核心配置项解析include: 指定哪些路径交给 commonjs 插件处理默认[node_modules/**]但有时需缩小范围避免误伤exclude: 排除哪些路径如已确认是 ESM 的包排除可提速transformations: 是否启用高级转换如require-importdefaultIsModuleExports:最关键控制module.exports xxx是否生成export default xxx。设为true强制生成false则只生成命名导出。实操配置针对_freeGlobal.js类问题import commonjs from rollup/plugin-commonjs; export default defineConfig({ plugins: [ // 在 vite 默认插件后插入确保覆盖 commonjs({ include: [/node_modules\/lodash/, /node_modules\/rc-util/], // 精准定位不扫全量 exclude: [/node_modules\/lodash-es/, /node_modules\/ant-design/], // 排除已知 ESM 包 // 关键允许 module.exports xxx 生成 default 导出 defaultIsModuleExports: true, // 关键忽略 require() 动态调用警告很多老包用 require 加载 JSON ignore: [fs, path, os], // 关键为特定文件提供自定义转换 transforms: { // 对 _freeGlobal.js 这类纯赋值文件强制注入 default 导出 lodash/_freeGlobal.js: (code) { return code.replace(module.exports freeGlobal;, export default freeGlobal;); } } }) ] });为什么defaultIsModuleExports: true能解决问题它告诉 commonjs 插件“即使module.exports xxx的右边是表达式也请强行生成export default xxx”。对于_freeGlobal.js插件会将其转换为// 转换后 const freeGlobal typeof global object global global.Object Object global; export default freeGlobal;完美匹配import freeGlobal from lodash/_freeGlobal。避坑经验defaultIsModuleExports: true有风险如果某个 CJS 文件module.exports是一个对象如module.exports { a: 1, b: 2 }开启后会生成export default { a: 1, b: 2 }但你的代码可能是import { a } from xxx这会导致a为undefined。所以务必配合include精准限定范围只对已知是单值导出的文件开启。transforms是终极手段但维护成本高。每次包更新_freeGlobal.js路径可能变需同步更新。建议只用于临时救急长期方案仍是推动上游发 ESM 版。3.3 类型三包存在exports字段但配置冲突需手动补全推荐指数 ★★★☆☆有些包如dayjs,mitt虽有exports字段但字段结构不标准或 Vite 的解析器未能正确识别。典型表现是import dayjs from dayjs正常但import relativeTime from dayjs/plugin/relativeTime报default not exported。根因分析exports字段的嵌套层级或条件不匹配 Vite 的解析逻辑。例如dayjs的package.json有exports: { .: { import: ./esm/index.js, require: ./index.js }, ./plugin/relativeTime: { import: ./plugin/relativeTime/index.js, require: ./plugin/relativeTime/index.js } }但./plugin/relativeTime/index.js本身是 CJS 格式exports字段只指定了入口路径没指定该路径下的模块类型。Vite 读取到./plugin/relativeTime/index.js后仍会走默认的 CJS 解析流程从而触发default报错。解法在resolve.alias中为子路径显式指定 ESM 入口export default defineConfig({ resolve: { alias: { // dayjs 插件的 ESM 入口通常在 esm/ 目录下 dayjs/plugin/relativeTime: dayjs/esm/plugin/relativeTime, dayjs/plugin/customParseFormat: dayjs/esm/plugin/customParseFormat } } });验证方法进node_modules/dayjs/esm/plugin/relativeTime确认该文件是export default ...格式。如果是则alias生效。避坑经验不是所有包都有esm/目录。需手动进node_modules/xxx查看结构。常见规律esm/、dist/esm/、src/如果包是 TS 编译的。alias路径必须精确到文件不能只写目录。dayjs/plugin/relativeTime: dayjs/esm/plugin/relativeTime会映射到index.js但dayjs/plugin/relativeTime: dayjs/esm/plugin/relativeTime/index.js更稳妥。3.4 类型四私有包或无法升级的遗留包需源码级 patch推荐指数 ★★☆☆☆当以上方案均失效如公司内部一个十年老包作者已离职且无 ESM 计划唯一办法是在构建前自动 patch 其源码。这不是最佳实践但生产环境救火必备。原理利用 Vite 的build.beforeWriteBundle钩子在 Rollup 打包前扫描并修改node_modules中的目标文件。实操脚本patch-cjs.js// patch-cjs.js import fs from fs; import path from path; const PATCHES [ { // 匹配 lodash/_freeGlobal.js pattern: /node_modules\/lodash\/_freeGlobal\.js$/, replace: (content) { // 将 module.exports xxx; 替换为 export default xxx; return content.replace( /module\.exports\s*\s*([^;]);/, export default $1; ); } }, { // 匹配 rc-util/lib/warning.js pattern: /node_modules\/rc-util\/lib\/warning\.js$/, replace: (content) { // 添加 export default if (!content.includes(export default)) { return content \nexport default warning;; } return content; } } ]; export function patchCjs() { return { name: patch-cjs, buildStart() { PATCHES.forEach(({ pattern, replace }) { const files findFiles(pattern); files.forEach((file) { try { let content fs.readFileSync(file, utf8); const patched replace(content); if (content ! patched) { fs.writeFileSync(file, patched, utf8); console.log(✅ Patched ${file}); } } catch (e) { console.warn(⚠️ Failed to patch ${file}:, e.message); } }); }); } }; } function findFiles(pattern) { const results []; const walk (dir) { fs.readdirSync(dir).forEach((f) { const fullPath path.join(dir, f); if (pattern.test(fullPath)) { results.push(fullPath); } else if (fs.statSync(fullPath).isDirectory()) { walk(fullPath); } }); }; walk(node_modules); return results; }在vite.config.ts中引入import { patchCjs } from ./patch-cjs.js; export default defineConfig({ plugins: [patchCjs()] });为什么这是最后手段node_modules是 npm/yarn/pnpm 的管理区域手动修改会被下次install覆盖。因此patchCjs必须在每次vite build时执行形成“构建时 patch”。它破坏了依赖的不可变性CI/CD 环境需确保patch-cjs.js脚本稳定。建议将 patch 规则写入package.json的scripts如prebuild: node patch-cjs.js。避坑经验patch-cjs.js必须用 CommonJS 格式.js后缀因为 Vite 插件钩子在 Node.js 环境执行ESM 的import fs from fs在某些 Node 版本下会报错。findFiles函数要递归搜索因为node_modules里可能有多个版本的同一包hoisting 导致。每次 patch 后务必console.log确认成功否则静默失败会让你以为问题解决了实际没生效。4. 预防机制从项目初始化就切断“方言”传播链解决一次报错是救火建立预防机制才是治本。我在三个中大型 Vue3 项目中推行了一套“ESM 优先”规范上线半年内此类报错归零。4.1 初始化阶段用create-vuepnpm构建纯净基线create-vueVite 官方脚手架默认生成的项目已规避大部分 CJS 陷阱但还需强化强制使用 pnpmpnpm的 strict hoisting 机制能天然减少node_modules中的重复包和版本碎片。对比npm install可能生成node_modules/lodash和node_modules/rc-util/node_modules/lodash两个副本pnpm会统一链接到同一份降低 CJS 冲突概率。初始化时禁用--legacy-peer-deps该 flag 会跳过 peerDependencies 检查可能导致安装不兼容的 CJS 版本。宁可报错也要暴露依赖冲突。4.2 依赖管理建立“ESM 白名单”与“CJS 黑名单”在团队 Wiki 或README.md中维护两份清单ESM 白名单优先选用lodash-es替代lodashdate-fns替代momentvaltio替代zustand更轻量 ESMiconify/vue替代ant-design/icons-vue纯 ESM 图标库CJS 黑名单禁止直接 importlodash必须用lodash-esmoment必须用date-fns或dayjsuuidv3/v4必须用uuidv9 或crypto.randomUUID()js-yaml必须用yaml其 ESM 支持更完善落地工具用 ESLint 插件eslint-plugin-import锁死规则// .eslintrc.cjs module.exports { rules: { // 禁止 import 黑名单包 no-restricted-imports: [ error, { paths: [ { name: lodash, message: Use lodash-es instead }, { name: moment, message: Use date-fns or dayjs instead } ] } ], // 强制命名导入避免 default 导入失败 import/no-named-as-default: error, import/no-named-as-default-member: error } };4.3 CI/CD 流水线增加“ESM 兼容性预检”在git push后的 CI 流程中加入一步静态检查提前拦截 CJS 风险# ci-check-esm.sh #!/bin/bash # 检查 package.json 中是否有黑名单包 if npm ls lodash moment uuid9.0.0 --depth0 2/dev/null | grep -q lodash\|moment\|uuid; then echo ❌ Found banned CJS packages in dependencies exit 1 fi # 检查 node_modules 中是否存在非 ESM 入口 if find node_modules -name package.json -exec grep -l main:.*\.js {} \; | grep -v esm\|dist/esm; then echo ⚠️ Found CJS main entry in node_modules # 不退出仅警告因有些包无法避免 fi接入 GitLab CI 或 GitHub Actions让每次 PR 都自动执行。既教育新人又防止历史债务蔓延。5. 深度原理Rollup 的模块解析链路与commonjs插件工作流要真正掌控这个问题必须理解 Vite 底层 Rollup 的模块解析全过程。这不是玄学而是一条清晰的流水线。5.1 Rollup 的五层解析链路从 import 到 AST当你写import debounce from lodash/debounceRollup 会依次经过Resolve 阶段根据resolve.alias、resolve.dedupe、package.json.exports、package.json.main等规则确定最终加载的文件路径。例如lodash/debounce可能被解析为node_modules/lodash/debounce.js或node_modules/lodash-es/debounce.js。Load 阶段读取该文件的原始字符串内容。此时内容还是纯文本未解析。Transform 阶段按插件注册顺序依次调用transform钩子。rollup/plugin-commonjs就在此阶段介入将 CJS 代码转为 ESM。Parse 阶段Rollup 自身将转换后的代码解析为 AST抽象语法树提取import/export声明。Analyze 阶段分析 AST构建模块依赖图检查导出是否匹配import请求。若请求default但 AST 中无export default则抛出MISSING_EXPORT错误。关键洞察default is not exported错误发生在第 5 步但根因在第 3 步transform未生成export default或第 1 步resolve选错了 CJS 入口。5.2rollup/plugin-commonjs的转换逻辑详解该插件不是简单地“把module.exports替换成export default”它有一套复杂的决策树graph TD A[输入 CJS 文件] -- B{是否有 exports.default?} B --|是| C[直接生成 export default] B --|否| D{是否有 module.exports literal/function/class?} D --|是| E[生成 export default] D --|否| F{是否有 exports.xxx yyy?} F --|是| G[生成 export const xxx yyy] F --|否| H[生成 export default undefined]而_freeGlobal.js卡在 D 分支module.exports typeof global object global global.Object Object global;中的右边是表达式非 literal/function/class所以插件认为“不安全”跳过export default只留下exports空最终导致MISSING_EXPORT。defaultIsModuleExports: true的作用就是强制跳过 D 分支的判断直接走 E 分支。5.3 Vite 的resolve配置如何影响链路起点很多人以为resolve.alias只是字符串替换其实它是Resolve 阶段的最高优先级规则。其匹配顺序是resolve.alias完全匹配优先级最高package.json.exports按conditions匹配package.json.moduleESM 入口package.json.mainCJS 入口index.js兜底所以当你配置alias: { lodash: lodash-es }Rollup 根本不会去读lodash的package.json直接解析lodash-es的exports字段从源头绕过 CJS。6. 实战复盘一个真实案例的完整解决路径去年 Q3我接手一个 Vue3 Vite 的后台管理系统构建时报错“default” is not exported by “node_modules/ant-design/icons-vue/node_modules/rc-util/lib/warning.js”按前述方法我们走了完整闭环Step 1日志定位DEBUGrollup* vite build | grep warning.js显示错误来自rc-util/lib/warning.js。Step 2依赖树分析npm ls rc-util发现ant-design/icons-vue6.1.0依赖rc-util5.38.0而rc-util5.38.0的lib/warning.js内容是function warning(valid, message) { ... } if (process.env.NODE_ENV ! production) { module.exports warning; } else { module.exports function() {}; }典型的条件导出module.exports不是静态值commonjs插件拒绝生成default。Step 3方案选型rc-util无 ESM 版本官网未发布commonjs配置defaultIsModuleExports: true会破坏其条件逻辑else分支的空函数也会被导出alias无法精准到lib/warning.jsrc-util无esm/目录→ 选择类型四源码 patchStep 4编写 patch在patch-cjs.js中添加{ pattern: /node_modules\/rc-util\/lib\/warning\.js$/, replace: (content) { // 保留原有逻辑只添加 export default return content \nexport default warning;; } }Step 5CI 集成将patch-cjs.js加入package.jsonscripts: { prebuild: node patch-cjs.js, build: vite build }Step 6长期治理向ant-design/icons-vue提交 Issue推动其升级rc-util到v6已内置 ESM 支持同时团队内部将ant-design/icons-vue替换为iconify/vue。结果构建时间缩短 12%后续三个月零同类报错。更重要的是团队建立了patch-cjs.js的维护 SOP每次新增 CJS 依赖先查 npm再查node_modules最后决定是升级、alias 还是 patch。这个案例印证了一个原则没有银弹只有分层防御。配置是盾patch 是矛而预防机制是城墙。三者缺一不可。我在实际操作中发现最有效的组合是日常开发用pnpmESM 白名单预防CI 用ESM 预检拦截救火时用DEBUG 日志定位 commonjs精配实在不行再patch。这套组合拳下来Vite 打包的稳定性提升了一个数量级。