TypeScript模块解析策略Node与Classic的路径查找差异

TypeScript 编译器在处理 import 语句时，需要根据导入的字符串路径去磁盘上寻找对应的物理文件。这个过程被称为“模块解析”。选择错误的解析策略会导致明明文件存在，却报错“找不到模块”的情况。TypeScript 提供了两种主要的解析策略：Classic（经典）和 Node（节点）。了解两者的差异，是配置 tsconfig.json 的必修课。

配置模块解析策略

在使用任何解析策略之前，必须在项目的 tsconfig.json 文件中明确指定 moduleResolution 选项。

1. 打开项目根目录下的 tsconfig.json 文件。
2. 定位到 compilerOptions 对象内部。
3. 添加或修改 moduleResolution 字段。
   • 若需使用 Classic 策略，设置值为 "classic"。
   • 若需使用 Node 策略，设置值为 "node"（这是 CommonJS 项目的标准推荐值）。

配置示例代码如下：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node", 
    "strict": true
  }
}

Classic 策略的查找逻辑

Classic 策略是 TypeScript 早期为了兼容旧版简单项目而设计的。它的查找规则相对简单且“线性”，主要用于与 .d.ts 声明文件的旧版查找逻辑兼容。

1. 相对导入的查找

假设有一个文件路径为 /root/src/folder/A.ts，其中包含代码 import { B } from "./B"。

1. 尝试匹配同名的 .ts 文件。
   • 编译器查找 /root/src/folder/B.ts。
2. 尝试匹配同名的 .d.ts 声明文件。
   • 编译器查找 /root/src/folder/B.d.ts。

2. 非相对导入的查找

假设文件路径为 /root/src/folder/A.ts，其中包含代码 import { B } from "B"。注意，这里没有 ./ 前缀。

1. 在当前目录查找。
   • 编译器查找 /root/src/folder/B.ts。
   • 编译器查找 /root/src/folder/B.d.ts。
2. 逐级向上查找目录。
   • 编译器查找 /root/src/B.ts。
   • 编译器查找 /root/src/B.d.ts。
   • 编译器查找 /root/B.ts。
   • 编译器查找 /root/B.d.ts。
   • 持续向上直到系统根目录。

核心特点：Classic 策略在处理非相对导入（如 import "jquery"）时，完全忽略 node_modules 文件夹。它只会傻傻地在当前目录和父目录中找文件。

Node 策略的查找逻辑

Node 策略模仿了 Node.js 运行时的模块解析机制。这是目前前端开发中最常用的策略，因为它能够正确识别 node_modules 中的包。

1. 相对导入的查找

假设文件路径为 /root/src/folder/A.ts，包含 import { B } from "./B"。

1. 尝试匹配文件。
   • 编译器查找 /root/src/folder/B.ts。
   • 编译器查找 /root/src/folder/B.tsx（若启用了 jsx）。
   • 编译器查找 /root/src/folder/B.d.ts。
2. 尝试匹配目录（若上述文件不存在）。
   • 编译器查找 /root/src/folder/B/package.json。
   • 读取其中的 types 或 typings 字段作为入口文件。
   • 若无 package.json，查找 /root/src/folder/B/index.ts。
   • 查找 /root/src/folder/B/index.d.ts。

2. 非相对导入的查找

假设文件路径为 /root/src/folder/A.ts，包含 import "jQuery"。这是 Node 策略与 Classic 策略最大的区别所在。

1. 在当前目录查找 node_modules。
   • 编译器查找 /root/src/folder/node_modules/jQuery.ts。
   • 编译器查找 /root/src/folder/node_modules/jQuery/package.json（解析 types 字段）。
   • 编译器查找 /root/src/folder/node_modules/jQuery/index.ts。
2. 逐级向上查找 node_modules。
   • 编译器跳转至父目录 /root/src/，查找 /root/src/node_modules/jQuery...。
   • 编译器跳转至父目录 /root/，查找 /root/node_modules/jQuery...。
   • 持续向上直到系统根目录。

为了更直观地展示 Node 策略下非相对导入的查找流程，请参考以下逻辑图：

Classic 与 Node 的核心差异对比

为了快速理解两者的区别，请参考下表。

常见问题排查步骤

当你遇到 TS2307: Cannot find module 错误时，按照以下步骤排查，通常能解决 90% 的问题。

1. 检查 tsconfig.json 中的 moduleResolution 是否为 node。
   • 如果你在使用第三方库（如 lodash），但配置却是 classic，编译器永远找不到 node_modules 里的文件。修改为 node。
2. 确认导入语句是否使用了正确的相对路径前缀。
   • 导入自己的文件：必须使用 ./ 或 ../ 开头（例如 import "./utils"）。
   • 导入 node_modules 里的库：禁止使用 ./ 开头（例如 import "lodash"）。
3. 检查 package.json 中的入口字段。
   • 如果是开发一个 npm 包，确保 package.json 中包含 types 或 typings 字段，并指向正确的声明文件路径。
   • 如果没有 types 字段，Node 策略会尝试寻找 index.d.ts，确保该文件存在于包的根目录下。
4. 查看 baseUrl 和 paths 配置。
   • 如果使用了路径映射（如 import "@src/utils"），确保 tsconfig.json 的 compilerOptions 中正确配置了 baseUrl 和 paths。这会覆盖默认的 Node 查找逻辑。