JavaScript / TypeScript / 系统课时
模块解析基础
模块解析基础
写下 import 后,TypeScript 还要判断模块说明符对应哪个文件或类型声明。本节从相对路径、包名和 tsconfig.json 三个入口理解解析过程,并用 --traceResolution 查看真实查找证据。
学习目标
- 区分相对模块说明符与包模块说明符的查找路径
- 理解
module、moduleResolution与package.json对解析结果的影响 - 使用
--traceResolution定位“找不到模块”类问题
编译器解析的对象
import "./math.js" 和 import "some-package" 看起来都在导入模块,但查找起点不同。相对说明符从当前文件位置出发;包名说明符通常进入 node_modules,再结合包的 package.json、导出映射和类型声明确定入口。
moduleResolution 决定“按什么规则找”,module 决定“按什么模块系统理解并生成代码”。在现代 Node.js ESM 项目中常用 NodeNext;由 Vite、Rollup、esbuild 等打包器处理运行时加载时,常见选择则是 bundler。

NodeNext 与 bundler 的关键差异
| 场景 | 常见配置 | 需要注意 |
|---|---|---|
| Node.js 原生 ESM | module: "NodeNext"、moduleResolution: "NodeNext" |
相对导入通常要写运行时可用的扩展名,如 ./math.js |
| 由打包器处理模块 | module: "ESNext"、moduleResolution: "bundler" |
可按打包器习惯使用扩展名省略等写法,但最终行为由打包器决定 |
不要把 moduleResolution 理解成“TypeScript 会替你加载模块”。它只负责在编译期找到源文件和类型信息;Node.js、浏览器或打包器仍负责运行时加载。
用 traceResolution 查看查找过程
为了固定为 Node.js ESM 场景,先创建 package.json:
{
"type": "module"
}再使用下面的 tsconfig.json。这两个配置共同决定当前 .ts 文件按 ESM 与 NodeNext 规则处理:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true
},
"include": ["src/**/*.ts"]
}创建被导入模块。片段示例(需与后续入口文件及上述配置一起使用):
// src/math.ts
export function square(value: number): number {
return value * value;
}再创建入口文件。片段示例(需与上面的模块文件一起用于解析验证):
// src/index.ts
import { square } from "./math.js";
console.log(square(5));执行解析跟踪:
npx tsc --traceResolution --noEmit预期输出会包含类似的成功解析记录,具体行数和措辞会随 TypeScript 版本及实际路径变化:
======== Resolving module './math.js' from '<PATH>/src/index.ts'. ========
...
======== Module name './math.js' was successfully resolved to '<PATH>/src/math.ts'. ========<PATH> 代表项目的实际绝对路径。这个结果说明编译器接受运行时说明符 ./math.js,并在类型检查阶段找到了对应的 math.ts 源文件。
找不到模块时按证据排查
遇到 Cannot find module 时,先看模块说明符是否拼写正确,再检查当前项目的 module 与 moduleResolution 是否匹配运行环境。包导入失败时继续确认依赖是否安装,以及包的 exports、types 或声明文件是否真的暴露了目标入口。
还要注意 paths 主要改变 TypeScript 的查找方式,通常不会替你重写最终输出中的导入路径。如果运行时并不知道这些别名,就仍可能出现“编译能通过、启动却失败”的情况。模块解析配置必须同时服务于编译器和真实运行环境,而不能只让编辑器不报红。