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 决定导入说明符如何查找源码、声明文件和包 编译时报找不到模块,或编译规则与真实运行时不一致

module 与模块解析的职责链

用 NodeNext 建立可运行基线

现代 Node.js 同时支持 ESM 与 CommonJS,并根据文件扩展名和最近的 package.json 中 "type" 等信息判断模块格式。面向 Node.js 原生模块系统时,使用 NodeNext 能让 TypeScript 按接近 Node.js 的规则检查和输出代码。:contentReference[oaicite:1]{index=1}

先在项目根目录创建 package.json:

json
{
  "type": "module"
}

再创建 tsconfig.json:

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true
  },
  "include": ["src/**/*.ts"]
}

下面是完整的双文件示例,按注释中的路径分别保存:

ts
// src/math.ts
export const answer = 42;

// src/index.ts
import { answer } from "./math.js";

console.log(`answer=${answer}`);

编译并运行:

bash
npx tsc -p tsconfig.json && node dist/index.js

预期输出

text
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 的宿主。这样编译通过才更接近“运行时也能找到并正确加载模块”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

module 与模块解析

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通