TypeScript 模块解析：tsconfig.json 中的 moduleResolution

TypeScript 编译器在遇到 import 语句时，需要知道去哪里寻找对应的物理文件。这个寻找路径的规则完全由 tsconfig.json 中的 moduleResolution 选项控制。配置不匹配会直接触发“找不到模块”的编译阻断。

模块解析决定编译器如何将代码中的导入路径翻译成磁盘上的实际文件地址。

打开项目根目录下的 tsconfig.json 配置文件。
定位 "compilerOptions" 对象块，该块承载所有编译行为控制。
识别 "moduleResolution" 字段。该字段指定编译器遵循的文件查找算法。
理解默认查找顺序。编译器会依次尝试：当前目录匹配 -> 向上追溯父目录 -> 进入 node_modules 查找依赖包 -> 匹配类型声明文件（.d.ts）。

不同运行环境和打包工具对路径的容忍度不同。根据项目实际技术栈，对照下表选定唯一策略。

策略名称	核心规则说明	适用场景
`node16` 或 `nodenext`	严格遵循现代 Node.js 模块标准。导入路径必须显式写明 `.js` 或 `.mjs` 后缀。启用 `package.json` 的 `exports` 字段（控制包对外暴露的具体入口）。	Node.js 16 及以上的后端服务、全栈框架（Next.js / Remix / Astro）。
`bundler`	模拟现代前端打包工具（Vite / Webpack / Rollup）的容错行为。自动忽略文件后缀，跳过 Node.js 特有的 `exports` 限制，按直觉补全路径。	纯浏览器端单页应用（Vue / React 项目）、无需在 Node 环境直接运行的前端库。
`node10` （历史默认）	沿用旧版 CommonJS 规范。支持隐式补全 `.js`、`.json`、`.node` 后缀。无法识别新版 `exports` 字段映射。	遗留的 Node.js 14 及以下项目、无需 ESM 兼容的传统服务端代码。
`classic`	废弃的早期 TypeScript 专属规则。仅在特定相对路径下查找。	仅限维护 TypeScript 1.x 时代的古董项目。

配置前务必核对表格中的“适用场景”，勾选唯一匹配项进入下一步。

将选定的策略写入配置，并确保关联参数保持一致。

备份当前配置。在终端运行 cp tsconfig.json tsconfig.backup.json 生成安全快照。
清理旧字段。删除 tsconfig.json 中 compilerOptions 内原有的 moduleResolution 键值对（若存在）。
写入新策略。例如配置现代浏览器项目，插入如下代码：
```
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}
```
对齐模块输出格式。moduleResolution 必须与 module 字段语义匹配。若使用 bundler 或 nodenext，将 module 设为 ESNext 或 NodeNext；若使用 node10，将 module 设为 CommonJS 或 NodeNext。
保存文件变更。

通过编译反馈确认解析链路是否通畅。

运行类型检查。在终端执行 npx tsc --noEmit 触发全量校验。
观察控制台输出。若出现 error TS2307: Cannot find module...，立即进入深度排查。
开启路径追踪。在 tsconfig.json 的 compilerOptions 中临时添加 "traceResolution": true。
重跑检查命令。再次执行 npx tsc --noEmit，终端将逐行打印完整的路径试探过程。
读取日志节点。查找包含 ======== Resolving module 的区块，向下追踪至第一条 File '...' does not exist 的提示行。
修正源码路径。根据断点提示，补全缺失的文件后缀，或调整 ../ 相对层级。
清理调试开关。验证通过后，立即删除 "traceResolution": true，避免编译性能损耗。

针对特定策略的硬性要求，调整编码习惯以通过编译。

补全 ESM 环境后缀。使用 nodenext 策略时，TypeScript 源码虽为 .ts，但导入语句必须显式书写 .js。将 import { fn } from './helper' 改为 import { fn } from './helper.js'。
声明第三方无类型库。引入未提供 .d.ts 的旧库时，在项目根目录新建 src/types/shim.d.ts 文件，输入 declare module "缺失模块名"; 阻断报错。

映射复杂路径别名。若模块嵌套过深，利用 baseUrl 与 paths 字段建立快捷通道。

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@api/*": ["services/api/*"],
      "@ui/*": ["components/ui/*"]
    }
  }
}

区分构建与运行差异。bundler 模式仅影响 TypeScript 编译阶段。若项目最终交由 Node.js 直接执行（如 node dist/server.js），必须切换至 nodenext 并严格遵循原生后缀与 exports 规范。