JavaScript / TypeScript / 系统课时
配置模块解析
配置模块解析
模块解析配置决定 TypeScript 如何把 import 对应到真实文件、声明文件和包入口。关键不是记住所有选项,而是先确认最终由 Node.js 还是打包器加载模块,再让 module、moduleResolution、文件扩展名和 package.json 的导出规则保持一致。
学习目标
- 根据 Node.js 直跑或前端打包环境选择模块配置
- 理解相对导入扩展名为何会影响 ESM 解析
- 判断包的
exports与类型入口如何限制可导入路径
先判断谁负责解析模块
TypeScript 会按你选择的策略模拟运行时或打包器的查找规则。代码最终直接交给 Node.js 执行时,应采用 Node 对 ESM 与 CommonJS 的规则;代码先进入 Vite、Webpack、Rollup 等打包器时,则应让 TypeScript 模拟打包器更宽松的解析行为。
| 运行方式 | module |
moduleResolution |
重点 |
|---|---|---|---|
| 现代 Node.js 直接运行 | NodeNext |
NodeNext |
遵守 Node 的 ESM/CJS、扩展名和包导出规则 |
| 前端或通用打包器处理 | ESNext |
bundler |
保留 ESM 语法,由打包器处理扩展名与产物 |

配置 Node.js ESM 项目
下面以 Node.js ESM 为例。package.json 用 type 声明普通 .js 文件按 ESM 解释,TypeScript 则使用成对的 NodeNext 配置模拟同一套运行时规则。
{
"type": "module"
}这项配置会影响同目录下 .ts 对应输出文件的模块格式判断;它不是 TypeScript 独立决定的。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true
},
"include": ["src/**/*.ts"]
}创建两个源文件。注意 index.ts 导入时写的是运行后真实存在的 .js 扩展名,TypeScript 在检查阶段仍能把它关联到 math.ts。
// src/math.ts
export function add(a: number, b: number): number {
return a + b;
}// src/index.ts
import { add } from "./math.js";
console.log(add(2, 3));在已安装 TypeScript 的项目中编译并运行:
npx tsc && node dist/index.js预期输出:
5理解扩展名与包导出
在 Node.js ESM 中,TypeScript 通常不会替你改写导入字符串,因此源代码写 ./math.js 是在描述运行时产物,而不是说源码目录里必须存在 math.js。如果写成 ./math,打包器往往能补扩展名,但 Node ESM 的解析规则可能直接拒绝它。
.mts 与 .cts 还能显式表达模块格式,并分别对应 .mjs 与 .cjs 产物。普通 .ts 则需要结合最近的 package.json 和模块配置判断最终格式。
第三方包还可能通过 exports 公开有限入口。即使包内部确实存在某个文件,只要该子路径未导出,现代解析策略就可能禁止直接导入。类型入口也可以与运行时代码分别指向 .d.ts 和 .js 文件。
{
"name": "example-lib",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
"./feature": {
"types": "./dist/feature.d.ts",
"default": "./dist/feature.js"
}
}
}因此,example-lib 与 example-lib/feature 是公开入口,而 example-lib/internal 不应因为磁盘上存在对应文件就被视为可用 API。
验证解析是否一致
配置完成后,先让编译器只做检查,不生成文件。这样能快速发现扩展名、包入口或模块模式不匹配的问题。
npx tsc --noEmit && echo "resolution ok"预期输出:
resolution ok如果仍出现“找不到模块”或“相对导入需要显式扩展名”,应依次核对最终运行环境、module 与 moduleResolution 是否成对、当前文件的 ESM/CJS 身份,以及依赖包的 exports 是否真的公开了目标路径。模块解析的正确标准始终是:TypeScript 能通过检查,同时生成或保留的导入在最终加载环境中也能成立。