5000 字长文深度解析 typescript 项目中的 esm 模块依赖问题

本篇文章来聊一下 ts 项目中的一个大坑，esm 模块依赖问题。一开始遇到这个问题觉得没什么，中文社区还是和之前一样只能找到只言片语，结果去外文社区里也是叫苦不迭，大家一脚深一脚浅的走的很痛苦，实在是没想到背后的水这么深。

所以本文就来整理一下我从头到尾遇到的所有问题，来把平时接触到关于 node 模块化方案的零碎知识点串联起来，希望可以让大家少走弯路。

开始探索

首先来搭建一个小 demo，找个空文件夹安装我们需要的依赖：

npm install ts-node typescript nanoid

然后完善一下项目，添加一个相当基础的 tsconfig.json：

{
    "compilerOptions": {
        "outDir": "dist",
        "skipLibCheck": true,
        "strict": true,
        "noEmit": false,
        "target": "ES5"
    },
    "include": [ "**/*.ts"],
}

然后在 package.json 里加入我们的 ts-node 执行命令，执行后 ts-node 就会去读 index.ts 并执行代码：

"scripts": {
    "dev": "ts-node --files ./index.ts",
    "build": "tsc"
}

现在环境准备就绪，接下来我们新建 index.ts：

const plus = (a: number, b: number): number => a + b;

console.log(plus(1, 1))

很简单，实现了一个加法函数。现在我们执行 npm run dev 就可以看到如下结果：

ok，可以运行，接下来我们复现问题，在一开始的时候我们安装了一个比较常用的包 nanoid。这个包很简单，就是生成一个跟 uuid 差不多的字符串，

nanoid() // 输出 V1StGXR8_Z5jdHi6B-myT

既然已经安装好了，现在咱在 index.ts 里调用一下：

import { nanoid } from "nanoid";
console.log(nanoid());

const plus = (a: number, b: number): number => a + b;
console.log(plus(1, 1));

然后运行 npm run dev：

E:\learn\ts-esm-juejin\node_modules\ts-node\dist\index.js:842
            return old(m, filename);
                   ^
Error [ERR_REQUIRE_ESM]: require() of ES Module E:\learn\ts-esm-juejin\node_modules\nanoid\index.js from E:\learn\ts-esm-juejin\index.ts not supported.
Instead change the require of index.js in E:\learn\ts-esm-juejin\index.ts to a dynamic import() which is available in all CommonJS modules.
    at Object.require.extensions.<computed> [as .js] (E:\learn\ts-esm-juejin\node_modules\ts-node\dist\index.js:842:20)
    at Object.<anonymous> (E:\learn\ts-esm-juejin\index.ts:3:16)
    at Module.m._compile (E:\learn\ts-esm-juejin\node_modules\ts-node\dist\index.js:848:29)
    at Object.require.extensions.<computed> [as .ts] (E:\learn\ts-esm-juejin\node_modules\ts-node\dist\index.js:850:16)
    at async Promise.all (index 0) {
  code: 'ERR_REQUIRE_ESM'
}
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command npm run dev" terminated with exit code: 1.

这什么玩意，不能在 index.ts 里使用 require() 引用 es 包 nanoid？我哪里写 require 了？

原因在于 ts-node 是 先把你的代码编译成 js 代码，然后再交给 node 去执行（如果你不太了解的话可以去看一下上篇文章 typescript 的路径别名问题详解与前世今生 ）。

所以我们可以先执行 npx tsc 看一下（如果你在开发 ts 时遇到了问题，可以运行一下 tsc，如果编译通过了，就说明时 node 执行时出了问题，反之则代表是 ts 编译出了问题 ）：

可以看到，编译之后的代码里使用的是 require('nanoid')，所以 node 再执行之后才会报刚才那个错误。

现在我们深入一点，为什么使用 require 引入 nanoid 会报错？原因在于，nanoid 的最新版本 只支持 esm 导出格式。也就是说我们只能使用 import 来导入这个包。和 nanoid 类似还有 node-fetch 和 chalk，后两者的最新版也都宣布只支持 esm 导出格式。

好了，问题出现了，由于目前的打包目标是 CommonJS，所以现在有两条路可以走：

• 第一种是向前走，把目前项目的打包格式从 CommonJS 更新成 ESM。
• 另一种是向后走，把依赖的第三方包降级为尚且支持 CommonJS 的版本。

这两条路都是可以的，我们先来讲简单的。

依赖降级

如果你是在搞公司项目时遇到了这个问题的话，那最简单的办法就是把需要的依赖降级了。

具体做法也很简单，打开对应包的 npm 页面，找到版本，选择上一个大版本或安装人数最多的版本就好了：

因为只支持 esm 属于破坏性更新，所以遵守 语义化版本 的包基本都会直接更新一个大版本。

将项目升级为 esm

这条路上的坑就比较多了，我跌跌撞撞摔破了头才走到了最后，请大家系好安全带。

首先我们知道编译是 tsc 完成的，那么通过修改 tsconfig.json 就可以调整编译产物模式。所以我们可以修改下 compilerOptions 下的 module、target 字段来让编译后的代码直接使用 import 引入依赖。

{
    "compilerOptions": {
        // ...
        "module": "ES2022",
        "target": "Node16",
    },
    // ...
}

至于这两者的区别咱们下面再讲。现在我们 npm run dev 看一下：

D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843       
    return new TSError(diagnosticText, diagnosticCodes, diagnostics);
           ^
TSError: ⨯ Unable to compile TypeScript:
index.ts:1:24 - error TS2792: Cannot find module 'nanoid'. Did you mean to set the 'moduleResolution' option to 'node', or to add aliases to the 'paths' option?

1 import { nanoid } from "nanoid";
                         ~~~~~~~~

    at createTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843:12)
    at reportTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:847:19)
    at getOutput (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1057:36)
    at Object.compile (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1411:41)
    at Module.m._compile (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1596:30)
    at Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
    at Object.require.extensions.<computed> [as .ts] (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1600:12)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12) {
  diagnosticCodes: [ 2792 ]
}
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command npm run dev" terminated with exit code: 1.

好，换了个报错。可以看到它的提示里说指定 moduleResolution: node 有可能能修复这个问题。这是个坑，正确的做法应该是将其设置为 moduleResolution: Node16。

这里解释一下很多人困惑的地方，moduleResolution、module、target 的区别：

• moduleResolution 用于指定 typescript 如何去查找代码中引入的文件
• module 代表代码使用的模块化方案
• target 代表最终代码会被编译成哪个版本

单这么说可能会让人有点懵，咱们先从最简单的开始说起：

target 字段

这个字段代表着我们打包后的代码对应的 js 版本，所以 target 选项就是单纯的 ES 版本号：

但是最终的成果代码也不一定是对应版本的，target 字段标注了打包的大方向，一些细节会受到其他参数的影响，比如下面要讲的 module 字段.

---

module 字段

当前项目使用的模块化方案，所以其选项是 js 历史上出现过的模块化方案：

不熟悉的同学可能会有点懵，这怎么这么多 ESXXX？ node 模块化方案不就 CommonJS、ES6 和其他的一些老方案么？

欸，这你就有所不知了，ES6 的模块化方案也是随着 ES 版本的更迭在不断的进化的。例如 ES2020 新增了动态 import 和 import.meta。而 Node16 及以后的 NodeNext / ESNext 则增强了 esm 方案的兼容性，使其 可以原生引入使用 CommonJS 方案的模块。可以参考 TypeScript: TSConfig Reference 简单了解一下。

所以说，这些 ES 版本虽然都是在用 import / export，但是每个都有小小的差异，所以确实是不同的模块化方案。

回归正题，module 参数的优先级是比 target 高的，所以在打包到模块引入相关的代码时，会先使用 module 指定的方案，没有的话才会通过 target 找到对应的方案，例如 target:ES3 就会使用 CommonJS。这些在文档里都有标注：

---

moduleResolution

最后咱们来说一下这个 moduleResolution 是啥东西，它其实是指在打包时 如何搜索引入的文件，所以你可以看到它的选项就集中在几个差异比较大的方案上。

其中，Node 代表 CommonJS 方案，Node16 和 NodeNext 是 ESM 方案。而 Classic 方案则是 typescript 的锅，它在早期阶段（1.x 版本）实现的 import 引入逻辑和目前的 ESM 方案是有差异的，所以这个选项是为了向后兼容，新项目用不到。

这个选项的主要目的是为了应付日益复杂的 js 模块化方案。一个项目中可能会同时存在多个不同的模块化方案。而这个选项就提供了一个“逃生通道”，比如我想最后生成 esm 代码，但是在编译时使用 commonjs 的方案来引入其他模块。

继续探索

好了回归正题，我们现在的 tsconfig.json 应该是长这个样子：

{
    "compilerOptions": {
        "outDir": "dist",
        "skipLibCheck": true,
        "strict": true,
        "noEmit": false,
        "target": "ES2022",
        "module": "Node16",
        "moduleResolution": "Node16"
    },
    "include": [ "**/*.ts"]
}

好，现在继续 npm run dev：

D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843
    return new TSError(diagnosticText, diagnosticCodes, diagnostics);
           ^
TSError: ⨯ Unable to compile TypeScript:
index.ts:1:24 - error TS1471: Module 'nanoid' cannot be imported using this construct. The specifier only resolves to an ES module, which cannot be imported synchronously. Use dynamic import instead.

1 import { nanoid } from "nanoid";
                         ~~~~~~~~
    at createTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843:12)
    at reportTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:847:19)
    at getOutput (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1057:36)
    at Object.compile (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1411:41)
    at Module.m._compile (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1596:30)
    at Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
    at Object.require.extensions.<computed> [as .ts] (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1600:12)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12) {
  diagnosticCodes: [ 1471 ]
}
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command npm run dev" terminated with exit code: 1.

打脸啪啪响啊，这是又整了个花活，不过不要急，这是因为我们的 esm 项目改造还没完成。看一下报错，它说 只能在 ES module 中使用 import 引入模块 nanoid。难道说 node 觉得现在项目不是 esm？

没错，确实是这个原因。由于 esm 和 commonJS 方案的差异巨大。node 需要一些东西分辨 npm 安装的包是使用的哪个方案，这就是 package.json 的 type 字段：

可以看到，它的值只有两种，而 commonjs 则是 type 字段的默认值。所以说，我们需要显式指定 type: module 来让 node 可以知道这个项目是一个 esm 模块。

好了，加完之后我们再来 npm run dev 试一下，这次必成功！

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for D:\project\ts-esm-juejin\index.ts
    at new NodeError (node:internal/errors:371:5)
    at Object.file: (node:internal/modules/esm/get_format:72:15)
    at defaultGetFormat (node:internal/modules/esm/get_format:85:38)
    at defaultLoad (node:internal/modules/esm/load:13:42)
    at ESMLoader.load (node:internal/modules/esm/loader:303:26)
    at ESMLoader.moduleProvider (node:internal/modules/esm/loader:230:58)
    at new ModuleJob (node:internal/modules/esm/module_job:63:26)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:244:11)
    at async Promise.all (index 0)
    at async ESMLoader.import (node:internal/modules/esm/loader:281:24) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command npm run dev" terminated with exit code: 1.

又是个全新的报错，这什么鬼，无法识别的后缀名 ts？完全没有头绪啊。事实上，如果你刚才把 moduleResolution 设置为 node 也会报这个错。

我在这个地方卡了好几个小时，翻遍了 stackoverflow，最后终于发现这个问题是 ts-node 导致的，在 ts-node 文档 中可以看到：

Native ECMAScript modules

ts-node's ESM support is as stable as possible, but it relies on APIs which node can and will break in new versions of node. Thus it is not recommended for production.

You must set "type": "module" in package.json and "module": "ESNext" in tsconfig.json.

You must also ensure node is passed --loader. The ts-node CLI will do this automatically with our esm option.

注意最后一句话，由于 ts-node 默认使用的是 commonjs 方案解析依赖，所以如果我们采用 esm 方案时就不能用原来 ts-node 的调用方式了，具体都有哪些新方法原文中有讲，这里不在赘述，我选择下面的方案，修改 package.json，把 ts-node 换成 ts-node-esm 即可：

"scripts": {
    "dev": "ts-node-esm --files ./index.ts"
}

然后我们再执行 npm run dev：

哦感谢上帝！我们终于成功的跑通了代码！

不过你以为到这里就结束了？不不不，可怕的事情还在后面，还记得我们一开始写的那个加法函数 plus 么，现在我们把它挪到另一个文件 utils.ts 里，然后在 index.ts 里引用它：

utils.ts

export const plus = (a: number, b: number): number => a + b;

index.ts

import { nanoid } from "nanoid";
import { plus } from './utils'

console.log(nanoid());
console.log(plus(1, 1));

很正常对吧，现在执行 npm run dev：

D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843
    return new TSError(diagnosticText, diagnosticCodes, diagnostics);
           ^
TSError: ⨯ Unable to compile TypeScript:
index.ts:2:22 - error TS2835: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './utils.js'?

2 import { plus } from './utils'
                       ~~~~~~~~~
    at createTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843:12)
    at reportTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:847:19)
    at getOutput (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1057:36)
    at Object.compile (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1411:41)
    at transformSource (D:\project\ts-esm-juejin\node_modules\ts-node\src\esm.ts:400:37)
    at D:\project\ts-esm-juejin\node_modules\ts-node\src\esm.ts:278:53
    at async addShortCircuitFlag (D:\project\ts-esm-juejin\node_modules\ts-node\src\esm.ts:409:15)
    at async ESMLoader.load (node:internal/modules/esm/loader:303:20)
    at async ESMLoader.moduleProvider (node:internal/modules/esm/loader:230:47)
    at async link (node:internal/modules/esm/module_job:67:21) {
  diagnosticCodes: [ 2835 ]
}
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command npm run dev" terminated with exit code: 1.

新的报错！不过好在最后给出了解决方案，那就是给 utils 的引入文件加一个 .js 文件名：

import { nanoid } from "nanoid";
import { plus } from './utils.js';

console.log(nanoid());
console.log(plus(1, 1));

很离谱对吧，在一个 ts 项目中，代码都是在 ts 文件里编写的，现在引入的时候却需要加 js 后缀。这是什么逆天设定。

但是事实就是这样，让我们移步 Modules: ECMAScript modules | Node.js v16.15.1 Documentation (nodejs.org)，其中关于 module 引入的介绍是这样写的：

当使用相对路径时，文件后缀名是必须的。不仅如此，使用原生 esm 方案时，“引入文件夹时默认访问 index.ts 文件” 这个很方便的功能也不能用了，这里不再赘述，感兴趣的可以自己尝试一下。

这个变扭的感觉非常影响开发体验，如果你觉得 OK 的话，那么好，我们接下来就只剩下一个问题要解决了。

最终的问题：esm 引入 cjs 模块

一开始的时候我们提到，如果一个模块只支持 esm 的话，那我们就只能使用 import 来引入它。那么反过来，如果一个模块只支持 commonjs 的话，我们还能用 import 引入它么？

答案是可以，但不完全可以，下面来尝试一下，以我们非常熟悉的 lodash 为例，首先安装依赖：

npm install lodash @types/lodash

然后在 index.ts 里引入其中的 map 函数并调用：

import { nanoid } from "nanoid";
import { plus } from './utils.js';
import map from 'lodash/map';

console.log(nanoid());
console.log(plus(1, 1));
console.log(map([1, 2, 3, 4], (x) => x * 2))

然后执行 npm run dev 就可以看到如下报错：

D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843
    return new TSError(diagnosticText, diagnosticCodes, diagnostics);
           ^
TSError: ⨯ Unable to compile TypeScript:
index.ts:3:17 - error TS2307: Cannot find module 'lodash/map' or its corresponding type declarations.

3 import map from 'lodash/map';
                  ~~~~~~~~~~~~

    at createTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:843:12)
    at reportTSError (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:847:19)
    at getOutput (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1057:36)
    at Object.compile (D:\project\ts-esm-juejin\node_modules\ts-node\src\index.ts:1411:41)
    at transformSource (D:\project\ts-esm-juejin\node_modules\ts-node\src\esm.ts:400:37)
    at D:\project\ts-esm-juejin\node_modules\ts-node\src\esm.ts:278:53
    at async addShortCircuitFlag (D:\project\ts-esm-juejin\node_modules\ts-node\src\esm.ts:409:15)
    at async ESMLoader.load (node:internal/modules/esm/loader:303:20)
    at async ESMLoader.moduleProvider (node:internal/modules/esm/loader:230:47)
    at async link (node:internal/modules/esm/module_job:67:21) {
  diagnosticCodes: [ 2307 ]
}
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command npm run dev" terminated with exit code: 1.

错误提示找不到 lodash/map 这个模块，怎么会这样，这不是很常见的按需加载的写法么？你也可以尝试一下另一种经典写法 import { map } from 'lodash'，这个同样也会报错。

原因在于，lodash/map 是经典的 commonjs 代码拆分方案，我们访问这个模块时实际上是去查找 node_modules/lodash/map.js 这个文件。并且 lodash 在 package.json 只指定了 "main": "lodash.js"，所以在不借助其他打包工具的情况下，我们采用的 esm 方案是根本找不到这个 js 文件的，更别提解析其中的代码。

那么怎么解决这个问题呢？其实很简单，我们在一开始设置的时候在 tsconfig.json 里设置了 moduleResolution: Node16。为什么是 Node16？就是因为在这个版本 esm 提供了直接 import 原生 commonjs 包的功能！

我们可以在 node 的文档中看到：

使用 import 引用 cjs 模块时，会把其 moduel.exports 导出的对象解析为 esm 中的 export default。并且这种方式非常的可靠。

实际上，为了增强兼容性，esm 系统也会尝试把 exports 上的具名导出解析为对应的 import 解构写法，但是并不能保证其完全可靠，详细的内容推荐大家读一下 Modules: ECMAScript modules | Node.js v16.16.0 中的 Interoperability with CommonJS 小节，上面的引用就是出自这里。

所以说，我们只需要把上面的代码改写成直接 import 整个 lodash 就可以了：

import _ from 'lodash'

console.log(_.map([1, 2, 3, 4], (x: number) => x * 2))

再执行就可以看到输出了正确的结果，这里不再赘述。

当然，这种其实还是引入了整个 lodash，还有一种更简单的办法，我们可以在 lodash 的 README 里发现，它是提供了 esm 的包的：

Looking for Lodash modules written in ES6 or smaller bundle sizes? Check out lodash-es.

我们只需要安装 npm install lodash-es @types/lodash-es，然后就可以使用 import { map } from 'lodash-es' 来直接引入对应的小模块，这样对于减少打包体积有不少的帮助。

不过也不是所有的 cjs 包都有 esm 支持，像是 crypto-js 就没有。所以还是只能 import 整个包来使用。

---

到这里可能有些同学有些疑问，不太对啊，我记得平时引入包还是很轻松的，也没遇到过你上面说的各种问题啊。是的，主要是因为我们平时的打包目标都是 cjs，而且绝大多数包都会打包成支持多种模块化方案。像 nanoid 这种只支持 esm 的目前还是少数，不过随着时代的前进，这种包只会更多而不是更少。

如果你对于兼容多种模块方案感兴趣的话，可以去看一下这个工具 microbundle，它是基于 rollup 的零配置打包器，会根据你 package.json 里的 exports 字段的配置值来生成对应的包。

顺带一提，package.json 中的 exports 字段也是 node 标准的一部分，是从 node 12 引入的，文档在这里：Modules: Packages | Node.js v12.22.12 Documentation (nodejs.org)

总结

本篇文章简单介绍了下 ts 项目中的 esm 模块问题以及原因，要么简单一点依赖退版本，要么激进一点把自己升级成 esm。

可以看到，从上到下一共经历的七个不重样的报错，在了解了背后的原理后其实都不难，但是每当你以为找到了问题解决方法之后立马一个全新报错弹出来带来的挫败感真的很强。

而且网上搜索解决方案时，也不乏那些让你直接删除某些字段从而回退到 cjs 的方法存在。如果你稀里糊涂就用上的话，就会发现嗯？这个问题不是已经解决过了么？怎么又出来了？比如下面这位 271 赞的鬼打墙勇士（出处）：

实际上在开发前端项目时，由于工具链的完善，我们对 esm 的了解一般都仅限于了解 import / export 怎么使用。但是在 node 的非前端领域，模块依赖问题一下子就会暴露出来，特别是在使用了 ts 之后。

所以说，想要更深入的了解 nodejs，还是要不断拓宽自己的视野，不能仅限于前端写写页面，共勉。

参考

• Modules: Packages | Node.js v15.14.0 Documentation (nodejs.org)
• Error: unknown file extension .ts · Issue #1062 · TypeStrong/ts-node (github.com)
• 「建议收藏｜排坑」 如何在NodeJs中使用ESM模块化规范🐣 - 掘金 (juejin.cn)
• Can’t load TypeScript ESM files using ts-node/esm · Issue #7482 · dotansimha/graphql-code-generator (github.com)
• CommonJS vs native ECMAScript modules | ts-node (typestrong.org)
• Modules: ECMAScript modules | Node.js v18.4.0 Documentation (nodejs.org)
• 搭建一套支持TS的Node运行环境 - 简书 (jianshu.com)
• 使用ts-node运行ts脚本及踩过的坑 - 掘金 (juejin.cn)