Yarn PnP 与 ts-node 的 ESM 模块解析问题解析

问题背景

在现代 TypeScript 开发中，使用 ESM (ECMAScript Modules) 已成为趋势。然而，当结合 Yarn PnP (Plug'n'Play) 和 ts-node 时，开发者可能会遇到模块解析问题。具体表现为：当尝试通过 ts-node 运行包含相对路径导入（如 import { a } from './lib/a.js'）的 TypeScript 代码时，系统会抛出模块解析失败的错误。

技术栈分析

这个问题涉及三个关键技术：

1. Yarn PnP：Yarn 的依赖管理机制，通过虚拟文件系统而非传统的 node_modules 目录来管理依赖
2. ts-node：直接在 Node.js 中运行 TypeScript 代码的工具
3. ESM：JavaScript 的官方模块系统，支持显式文件扩展名

错误现象

当使用以下命令运行时：

yarn node --loader=ts-node/esm.mjs --loader=./.pnp.loader.mjs -- src/main.ts

系统会报错，提示无法解析 .js 文件路径。这是因为：

1. Yarn PnP 的加载器首先尝试解析 .js 文件
2. 但实际上开发者期望的是解析对应的 .ts 文件
3. 由于加载器顺序问题，解析过程被过早中断

根本原因

问题的核心在于加载器(loader)的执行顺序。在 Node.js 中，加载器是按照命令行中指定的顺序执行的。当同时指定 ts-node 和 PnP 加载器时：

1. 错误的加载顺序：PnP 加载器先于 ts-node 执行，会严格尝试解析 .js 文件
2. 正确的加载顺序：ts-node 应该先有机会将 .js 引用转换为 .ts 引用

解决方案

正确的命令应该是：

yarn node --loader=ts-node/esm.mjs -- src/main.ts

关键点：

• 不需要显式指定 PnP 加载器，因为 yarn node 命令已经自动设置了正确的 PnP 加载器
• PnP 加载器需要最接近默认加载器（即最后执行），这样才能正确处理模块解析

技术原理深入

1. Yarn PnP 的工作原理：PnP 通过替换 Node.js 的模块解析机制来实现无 node_modules 的依赖管理。它的加载器必须最后执行，才能正确处理所有特殊情况。

2. ts-node 的 ESM 支持：ts-node 的 ESM 加载器会智能地将 .js 引用转换为对应的 .ts 文件，但需要有机会处理这些引用。

3. Node.js 加载器机制：加载器是按照"洋葱模型"执行的，最先指定的加载器最外层，最后指定的最接近核心。

最佳实践建议

1. 使用 Yarn PnP 时，避免手动指定 PnP 加载器
2. 确保 ts-node 加载器先执行
3. 对于复杂的模块解析需求，考虑使用 tsconfig 中的路径映射
4. 保持工具链更新，特别是 Yarn 和 ts-node 版本

总结

这个问题展示了现代 JavaScript 工具链中模块解析的复杂性。通过理解 Yarn PnP 和 ts-node 的交互方式，特别是加载器的执行顺序，开发者可以避免这类问题。记住关键原则：让 yarn node 自动管理 PnP 加载器，而只显式指定其他必要的加载器。