JavaScript / TypeScript / 系统课时
module 与模块解析
module 与模块解析
module 和 moduleResolution 经常一起出现,却解决不同问题。这节课会把“编译成什么模块格式”和“导入路径如何找到文件”拆开,并用现代 Node.js 的 NodeNext 配置跑通一个最小项目。
学习目标
- 区分
module与moduleResolution各自负责的阶段 - 为现代 Node.js 项目配置可运行的
NodeNext模块策略 - 根据 Node.js 或打包器环境选择匹配的模块解析方式
先分清输出格式与查找算法
看到 import { answer } from "./math.js" 时,TypeScript 至少要回答两个问题:这条导入在输出 JavaScript 中应采用什么模块语义,以及 ./math.js 在类型检查阶段对应哪个源文件。module 主要描述运行环境使用的模块系统,并影响输出和类型检查;moduleResolution 则描述模块说明符如何解析到文件或包。:contentReference[oaicite:0]{index=0}
| 配置 | 主要职责 | 配错后的典型表现 |
|---|---|---|
module |
描述输出模块格式和运行时模块语义 | 输出语法与实际运行环境不匹配 |
moduleResolution |
决定导入说明符如何查找源码、声明文件和包 | 编译时报找不到模块,或编译规则与真实运行时不一致 |

用 NodeNext 建立可运行基线
现代 Node.js 同时支持 ESM 与 CommonJS,并根据文件扩展名和最近的 package.json 中 "type" 等信息判断模块格式。面向 Node.js 原生模块系统时,使用 NodeNext 能让 TypeScript 按接近 Node.js 的规则检查和输出代码。:contentReference[oaicite:1]{index=1}
先在项目根目录创建 package.json:
{
"type": "module"
}再创建 tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true
},
"include": ["src/**/*.ts"]
}下面是完整的双文件示例,按注释中的路径分别保存:
// src/math.ts
export const answer = 42;
// src/index.ts
import { answer } from "./math.js";
console.log(`answer=${answer}`);编译并运行:
npx tsc -p tsconfig.json && node dist/index.js预期输出
answer=42这里没有把源文件导入写成 ./math.ts。在 Node.js ESM 语义下,运行时相对导入需要可解析的文件扩展名;TypeScript 在 NodeNext 解析时可以用 ./math.js 对应到开发阶段的 math.ts,而编译后这条说明符仍然指向真正存在的 dist/math.js。
按真实运行环境选择策略
不要按“代码里写的是 import 还是 require”机械选配置,而应先确认最终由谁加载 JavaScript。TypeScript 官方配置参考也建议:现代 Node.js 通常使用 nodenext,由打包器处理的应用通常使用 preserve 或 esnext,并配合适合打包器的解析策略。:contentReference[oaicite:2]{index=2}
| 最终运行方式 | 常见选择 | 关键理由 |
|---|---|---|
| Node.js 原生运行 | module: "NodeNext" + moduleResolution: "NodeNext" |
同时建模 Node.js 的 ESM、CommonJS 和包解析规则 |
| Vite、Rollup、Webpack 等打包 | module: "ESNext" 或 "Preserve" + moduleResolution: "Bundler" |
让打包器负责最终路径与模块装配,并允许打包器常见的扩展名省略规则 |
| 历史 CommonJS 工具链 | 与实际工具链保持一致 | 旧项目应以真实加载器行为为准,不要只为消除编译错误随意混搭 |
moduleResolution: "Bundler" 支持现代 package.json 的 exports 和 imports,但不会像 Node.js ESM 那样强制相对导入写扩展名,因此它适合“最终一定由打包器处理”的代码,不适合拿来假装检查纯 Node.js 运行结果。
遇到解析错误时的定位顺序
先确认最终宿主是 Node.js、浏览器打包器还是其他运行器,再检查 module 与 moduleResolution 是否描述同一个环境。随后查看最近的 package.json 中 "type"、包的 exports 或 imports,以及相对导入是否使用了运行时真正存在的扩展名。
如果编译阶段仍报 TS2307,可以临时运行 npx tsc -p tsconfig.json --traceResolution 查看 TypeScript 尝试过的候选路径。若 TypeScript 能解析而运行时报模块不存在,问题通常已经不在类型检查层,而是编译器规则与 Node.js 或打包器的真实解析规则没有对齐。
配置模块系统的核心原则只有一个:让 TypeScript 模拟最终真正执行 JavaScript 的宿主。这样编译通过才更接近“运行时也能找到并正确加载模块”。