TypeScript 模块解析：Node 与 Classic 模式

TypeScript 模块解析：Node 与 Classic 模式

当你在 TypeScript 项目中看到 Cannot find module 或 Module not found 错误时，通常是因为编译器不知道如何根据你的 import 语句去寻找对应的文件。TypeScript 提供了两种主要的模块解析策略：Node 和 Classic。理解这两者的区别，能让你精准定位路径问题，不再被报错卡住。

1. 配置模块解析策略

所有的模块解析行为都受控于 tsconfig.json 配置文件。要修改或查看当前策略，执行以下步骤：

1. 打开项目根目录下的 tsconfig.json 文件。
2. 定位到 compilerOptions 字段。
3. 查找名为 moduleResolution 的属性。
   • 如果该属性不存在，默认值取决于 module 属性的值。当 module 为 CommonJS 时，默认为 Node；否则通常默认为 Classic（但在较新版本的 TypeScript 中，Node 已成为更通用的默认倾向）。
   • 确认其值为 "node" 或 "classic"。

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node", // 重点在这里
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

2. 理解 Classic 模式

Classic 模式是 TypeScript 早期的解析方式，主要用于向后兼容。它的逻辑相对简单，但处理非相对路径（即不以 ./ 或 ../ 开头的导入）时能力有限。

Classic 模式的解析逻辑

当你在代码中导入一个模块时：

1. 相对导入（如 import { A } from "./utils"）：

   • TypeScript 直接查找相对于当前文件的指定路径。
   • 如果找到 .ts、.tsx 或 .d.ts 文件，解析成功。
   • 如果路径指向的是一个文件夹，它会尝试查找该文件夹下的 index.ts、index.tsx 或 index.d.ts。

2. 非相对导入（如 import { A } from "utils"）：

   • TypeScript 不会去 node_modules 寻找。
   • 它会从包含导入文件的目录开始，逐级向上在目录链中查找名为 utils.ts、utils.tsx 或 utils.d.ts 的文件。

适用场景：仅在极少数极简项目或特定的老式构建流程中使用。

3. 理解 Node 模式（推荐）

Node 模式模仿了 Node.js 的运行时模块解析机制。这是目前绝大多数前端项目（React, Vue, Angular 等）的标准配置。它能够正确处理 node_modules 中的第三方库。

Node 模式的解析逻辑

Node 模式对相对导入的处理与 Classic 模式类似，但对非相对导入的处理截然不同。

1. 相对导入（如 import { A } from "./utils"）：

   • 查找完整文件名：先尝试 ./utils.ts，再尝试 ./utils.tsx，最后尝试 ./utils.d.ts。
   • 查找目录包：如果上述未找到，且存在 ./utils 目录：
     • 读取 ./utils/package.json，查看 types 或 typings 字段指定的文件。
     • 若无 package.json 或无字段，尝试查找 ./utils/index.ts、./utils/index.tsx 或 ./utils/index.d.ts。

2. 非相对导入（如 import * as _ from "lodash"）：

   • TypeScript 不会把 "lodash" 当作文件名去向上查找。
   • 它会沿着目录链向上查找，在每一级目录下的 node_modules 文件夹中寻找 lodash 文件夹。
   • 一旦找到 node_modules/lodash，后续逻辑与相对导入的“查找目录包”一致（检查 package.json 或 index 文件）。

为了更直观地展示 Node 模式下非相对模块的查找过程，请参考以下流程：

核心结论：如果你使用 npm 或 yarn 安装第三方包，务必使用 Node 模式，否则编译器无法找到位于 node_modules 中的库。

4. 两种模式的实战对比

假设项目目录结构如下：

/project
  /src
    /folderA
      fileA.ts
    /folderB
      fileB.ts
    utils.ts
  tsconfig.json
  /node_modules
    /lib
      index.d.ts

在 /src/folderA/fileA.ts 中，我们尝试进行不同的导入。

5. 进阶配置：路径映射

在 Node 模式下，为了避免使用复杂的相对路径（如 ../../../../utils），我们可以结合 baseUrl 和 paths 配置项来实现类似 Webpack Alias 的功能。

1. 打开 tsconfig.json。
2. 设置 compilerOptions.baseUrl 为 "."（表示项目根目录）或 "./src"（表示源码目录）。
3. 添加 compilerOptions.paths 对象，键为路径别名，值为实际路径数组。

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@utils/*": ["utils/*"],
      "@core": ["core/index"]
    }
  }
}

此时，在任意文件中，import { foo } from "@utils/helper" 会被解析为 <baseUrl>/utils/helper。

注意：这种映射仅存在于 TypeScript 编译时。如果你的项目后续需要使用 Webpack 或 Vite 打包，你需要同步配置构建工具的别名设置，使其与 tsconfig.json 保持一致。