Modern.js 项目中 ESM 模块兼容性问题解析

问题背景

在使用 Modern.js 2.62.1 版本开发 BFF (Backend For Frontend) 服务时，开发者遇到了一个典型的模块系统兼容性问题。当尝试在项目根目录下的 api 目录中使用 @octokit/auth-oauth-user 这个纯 ESM 格式的包时，系统抛出了 TypeError 错误，提示无法识别 .ts 文件扩展名。

错误分析

错误信息显示系统无法处理 TypeScript 文件，这实际上反映了更深层次的模块系统兼容性问题。Modern.js 服务器默认以 CommonJS 格式运行，而 @octokit/auth-oauth-user 是一个纯 ESM 格式的包，这种不匹配导致了运行时错误。

解决方案

要解决这个问题，我们需要将整个项目转换为 ESM 格式，以下是具体步骤：

1. 修改 package.json 在项目的 package.json 中明确指定模块类型为 ESM：

   {
     "type": "module"
   }
   

2. 调整 TypeScript 配置 更新 tsconfig.json 文件以支持 ESM 模块：

   {
     "compilerOptions": {
       "module": "esnext",
       "moduleResolution": "bundler"
     }
   }
   

3. 文件导入规范 在 server、api 和 shared 目录中，所有相对路径导入都需要添加 .js 后缀：

   import type { Vars } from '../shared/index.js';
   

注意事项

1. 路径别名限制：在 ESM 模式下，server、api 和 shared 目录中不能使用 tsconfig 中定义的路径别名，这是当前的一个限制。

2. 模块选择建议：在选择第三方依赖时，优先考虑支持双模式（同时支持 CommonJS 和 ESM）的包，可以减少兼容性问题。

3. 渐进式迁移：对于大型项目，可以考虑逐步迁移到 ESM，而不是一次性全部转换。

技术原理

这个问题的本质是 Node.js 生态系统中 CommonJS 和 ESM 两种模块系统的差异。Modern.js 默认使用 CommonJS 是为了保证最大的兼容性，而越来越多的现代包（如 @octokit/auth-oauth-user）选择只提供 ESM 格式，以获得更好的 tree-shaking 和静态分析能力。

通过将项目明确标记为 ESM 格式，我们告诉 Node.js 运行时应该使用 ESM 的模块解析规则，从而能够正确处理纯 ESM 包的导入。

总结

Modern.js 作为一个现代化的全栈框架，同时支持 CommonJS 和 ESM 两种模块系统。理解这两种系统的差异并根据项目需求选择合适的配置，是保证项目顺利运行的关键。对于需要使用纯 ESM 包的项目，按照上述步骤配置可以有效地解决问题，同时也能享受到 ESM 带来的各种优势。