前言

传闻在JavaScript与TypeScript武林中，曾有两大绝世心法：CommonJS与ESM。两派高手比肩而立，各自称霸一方，江湖一度风平浪静。

岂料，时局突变。ESM逐步修成阳春白雪之姿，登堂入室，成为主流正统。CommonJS则渐入下风，功力不济，逐渐退出主舞台。

话说某日，一位前端少侠夜观天象，打算在项目中配置vite.config.js或vite.config.ts。本欲安稳修炼，却因一招不慎，引入require触犯禁忌，顿时屏幕黑闪、终端哀鸣：

错误 [ERR_REQUIRE_ESM]：你这个 require，不识我这 ESM？

少侠眉头紧锁，神情恍惚，仿佛被“代码反噬术”击中，功力尽失，调试无门，怀疑人生。

幸好你手持此篇《ESM内功心法》，得以步入正道。待少侠修炼完毕，自可畅行江湖，无惧require的逆袭，从此bug不侵，打包如风。

简介

先来普及一门武林秘籍，分清两派修行之道：

• require()：江湖流传多年的 CommonJS 内功心法，招式老练，直击依赖要害，出招迅速，信手拈来。
• ESM（ECMAScript Module）：新晋正统心法，W3C 亲授，讲究模块隔离、按需异步、规范至上，是未来之光、江湖正道。

自 Node.js 12 起（尤其 Node 14 以后），ESM 渐露峥嵘，在各大比武招亲大会上大放异彩。然而江湖深处，仍有不少老门派执念于 require，一路修行直到某日：

你施展 npm install，正欲引包入体，却只见门口贴着一纸告示：

「此包仅适用于 ESM！」

如同大门紧锁，只接待佩剑少年，令拿着 require 木棍的老弟子原地发呆，心灰意冷。

在 JS 或 TS 武林中，CommonJS 可谓 Node.js 的祖师爷，名震一方；而 ESM，则系 W3C 正统血脉，风头正劲，广受新派拥戴。

正因 ESM 出自后门，武功尚未全面打通五脉，在 Node.js 中尚需手动开坛设法。若在未修 ESM 心法之地妄图以 require() 调用 .mjs、.mts 或 "type": "module" 模块，终将引发模块冲突，引来错误天谴，令人头秃当场。

修炼之路虽难，唯有认清主线，方能不被卡在“require不通，ESM不识”的门派迷宫中。

遇到问题

某日深夜，小侠潜心修炼项目武学，正于vite.config.ts中布阵施法。眼见绝世依赖「xxx」静静躺在江湖之中，便使出熟悉套路：

怎料招式一出，顿时天雷勾动地火，终端仿佛被打通任督二脉后逆流而上，猛然喷出怒火红字：

霎时间风云变色，项目失控，控制台怒吼不止。师傅闻声而来，眉头紧蹙，语重心长：

“此乃修炼之误。require 路数已废，岂可轻用？你这出招，正是误闯 ESM 秘境！”

小侠满脸茫然，只觉内功倒流、配置失效，仿佛手中长剑突然变成塑料玩具，无力招架。

解决方案

曾几何时，require 是你最得心应手的武器，每当遇到敌人，便轻松拔剑：

然而，江湖风云变幻，ESM 流派崭露头角，原本的招式已显陈旧。此时，只需轻松一变，换用 ESM 流派的正宗武技：

此招虽简，却蕴含无限威力，适应未来的江湖规则。使用后，任你四方巡游，无往不利。

在 Node.js 版本 <= 22 中，默认无法使用 require 加载 ESM 文件。

虽然在使用
--experimental-require-module、Node.js > 22 或其他特定运行时中可能可行，但我们依然建议将配置转换为 ESM，以避免潜在兼容性问题。照此秘籍修炼，便可破除误入之困，稳步迈向前端正道：

方案一：声明门派

在 package.json 中加入以下代码，瞬间宣告你已加入“ESM 派”：

此举一出，Node.js 便会以全新眼光审视你，视若门派新星，功力大增。

方案二：改名换姓

想要真正转身为 ESM 派的高手，配置文件的名字必不可少！将你的配置文件改名为：

这乃点睛之笔，若不改，心法无法生效，功力无法提升。

搞笑故事

江湖传闻：前端大师兄为图速成，习惯用 require() 搭配 .mts 模块。次日清晨，打包上阵，Vite 报错如浪潮扑面，警告文字铺天盖地。项目经理怒声喝道：“上线竟然崩溃！”

大师兄望屏幕红字，心中惊惶。环视同僚，众人目光如炬，仿佛他瞬间被逐出江湖。双手在键盘上飞舞，却无力破解报错玄机。研读文档数遍，依旧迷雾重重，只得抱头痛哭。

无奈之下，他向群中侠士求助。一轮询问后，群友传来神仙口诀：

“ESM 当道，CommonJS 招式不够看！”

大师兄恍若醍醐灌顶，迅速取出手机，输入 /ask Xjbcm AI 指令。片刻之后，Xjbcm AI 回道：

“在 package.json 中设置 type: 'module'，将配置文件改为 .mjs 或 .mts，并以 import 替换 require。”

读罢如获神助，大师兄立刻翻新心法，一气呵成将 require 换为 import，重启打包。此时 Vite 平静如止水，项目顺利过关，启动速度骤然提升。

项目经理见状，眉头松弛，面露欣喜。众人见此奇迹，纷纷献花拜师，高呼：

“大师兄妙手回春！”

此事迅速传遍前端江湖，英雄豪杰竞相研习 ESM 心法。若有新入江湖之人仍用 require 直取 .mts，见此故事方知未来武学当在 import 之道。

大师兄在群里留下一句金句：

“共修 ESM 心法，项目稳如磐石，江湖无恙。”

此言一出，侠士心服口服，纷纷暗暗记下此传世秘闻，誓将此心法融入血脉，从此征战四方无碍！

注意事项

• Node 版本需 ≥ 14，建议使用 18+
• 若你的模块需要发布，需兼容 CommonJS 和 ESM，可使用 dual exports 格式
• 在某些 CLI 工具或测试框架中，也需对应支持（Jest 要用 babel-jest 配合）

总结

武功再高，也难挡 require 报错一指。眼下前端江湖已步入 ESM 盛世，CommonJS 渐渐归隐山林。欲立足武林之巅，唯有趁早修炼新心法，方能从容应对未来诸多挑战：

在 package.json 中配置 type: module

将配置文件改名为 .mjs 或 .mts

以 import 替换所有 require 招式

若某日你在群聊之中，听见有人一边 debug 一边哀嚎：“为啥 require 不管用？”别慌，淡定微笑，右手转发此文，左手轻点一句：

江湖险恶，修炼 ESM，方为正道。