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 与打包器的模块解析路径

配置 Node.js ESM 项目

下面以 Node.js ESM 为例。package.json 用 type 声明普通 .js 文件按 ESM 解释,TypeScript 则使用成对的 NodeNext 配置模拟同一套运行时规则。

json
{
  "type": "module"
}

这项配置会影响同目录下 .ts 对应输出文件的模块格式判断;它不是 TypeScript 独立决定的。

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

创建两个源文件。注意 index.ts 导入时写的是运行后真实存在的 .js 扩展名,TypeScript 在检查阶段仍能把它关联到 math.ts。

ts
// src/math.ts
export function add(a: number, b: number): number {
  return a + b;
}
ts
// src/index.ts
import { add } from "./math.js";

console.log(add(2, 3));

在已安装 TypeScript 的项目中编译并运行:

bash
npx tsc && node dist/index.js

预期输出:

text
5

理解扩展名与包导出

在 Node.js ESM 中,TypeScript 通常不会替你改写导入字符串,因此源代码写 ./math.js 是在描述运行时产物,而不是说源码目录里必须存在 math.js。如果写成 ./math,打包器往往能补扩展名,但 Node ESM 的解析规则可能直接拒绝它。

.mts 与 .cts 还能显式表达模块格式,并分别对应 .mjs 与 .cjs 产物。普通 .ts 则需要结合最近的 package.json 和模块配置判断最终格式。

第三方包还可能通过 exports 公开有限入口。即使包内部确实存在某个文件,只要该子路径未导出,现代解析策略就可能禁止直接导入。类型入口也可以与运行时代码分别指向 .d.ts 和 .js 文件。

json
{
  "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。

验证解析是否一致

配置完成后,先让编译器只做检查,不生成文件。这样能快速发现扩展名、包入口或模块模式不匹配的问题。

bash
npx tsc --noEmit && echo "resolution ok"

预期输出:

text
resolution ok

如果仍出现“找不到模块”或“相对导入需要显式扩展名”,应依次核对最终运行环境、module 与 moduleResolution 是否成对、当前文件的 ESM/CJS 身份,以及依赖包的 exports 是否真的公开了目标路径。模块解析的正确标准始终是:TypeScript 能通过检查,同时生成或保留的导入在最终加载环境中也能成立。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置模块解析

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

登录哪都通