在TypeScript项目里，一个import语句写下去，编译器到底去哪里找这个模块？这个问题看起来简单，背后却牵扯到tsconfig.json中一个关键配置项：moduleResolution。它决定了TypeScript如何把import的模块说明符解析成磁盘上的真实文件。官方提供了Classic和NodeJs两种策略，很多初学者在遇到“无法找到模块xxx”的报错时，往往就是因为不清楚这两种策略的查找规则差异，导致目录结构或配置文件写错了位置。
Classic策略的查找规则与适用场景
Classic是TypeScript早期默认的解析策略，它的设计目标是不依赖任何运行环境，纯粹从TypeScript自身的角度去查找类型文件。规则非常简单：对于相对导入（以./或../开头），Classic不做任何特殊处理，直接按相对路径查找；而对于非相对导入（比如import { Foo } from "utils"），Classic会从当前源文件所在的目录开始，逐级向上查找同名文件，直到根目录为止。
假设有如下目录结构：
/root/src/views/user/List.ts /root/src/utils.ts /root/utils.ts
如果List.ts中写的是import { helper } from "utils"，Classic策略会依次尝试查找/root/src/views/user/utils.ts、/root/src/views/utils.ts、/root/src/utils.ts、/root/utils.ts。只要其中任意一层存在匹配的.ts、.tsx或.d.ts文件，解析就成功。注意这个过程中Classic不会读取node_modules目录，也不会关心package.json文件。
这种策略的优点是查找速度快、规则简单，但它与Node.js的运行时行为严重脱节。在真实运行的Node环境中，模块是从node_modules里加载的，Classic根本找不到这些包，所以在使用第三方依赖的现代项目中，Classic几乎不可用。它主要适用于没有打包工具、纯TypeScript编译的老项目，或者某些通过环境变量动态查找类型的特殊场景。
NodeJs策略如何模拟Node的模块加载逻辑
NodeJs策略（在较新的TypeScript版本中也叫node10，新版本还提供了node16、nodenext等更精细的选项）完全模拟Node.js的CommonJS模块解析算法。对于相对导入，它同样按路径查找，但会额外尝试补全扩展名：先找精确文件名，再依次尝试.ts、.tsx、.d.ts，如果是目录还会读取其中的index文件。
它真正的威力体现在非相对导入上。当解析import { something } from "lodash"这样的语句时，NodeJs策略会从当前文件所在目录开始，逐级向上查找node_modules目录。找到后，会按照以下顺序定位模块的实际入口：
- 先查看node_modules/lodash/package.json中的types或typings字段指定的类型声明文件
- 如果types字段不存在，则尝试main字段对应的JavaScript文件，并在同目录下寻找同名.d.ts文件
- 如果都没有，则尝试node_modules/lodash/index.d.ts以及目录下的index.ts等入口文件
- 如果包内自带类型声明，会优先使用包内声明；否则查找@types/lodash
这个查找过程与Node.js运行时加载模块的逻辑保持一致，因此编译期能解析到的模块，运行期也基本能正确加载。这就是为什么在绝大多数Web项目、Node后端项目中，官方都推荐使用NodeJs策略。配置方式很简单：
{
"compilerOptions": {
"module": "commonjs",
"moduleResolution": "node"
}
}
需要注意的一点是，moduleResolution并不是孤立的配置。当module设置为commonjs、amd、umd或es2015等经典模块格式时，不显式指定的话默认值是Classic还是NodeJs会因TypeScript版本而有差异，所以最稳妥的做法是始终显式声明moduleResolution，避免隐式默认值带来的行为漂移。
两种策略的对比与常见报错排查
把两者的核心差异整理成表格，可以更直观地看出区别：
| 对比项 | Classic策略 | NodeJs策略 |
|---|---|---|
| 非相对导入查找方式 | 从当前文件目录逐级向上查找同名文件 | 逐级向上查找node_modules目录 |
| 是否支持node_modules | 不支持 | 支持 |
| 是否读取package.json | 不读取 | 读取types、main字段 |
| 是否模拟Node运行时 | 不模拟 | 完整模拟 |
| 适用场景 | 无依赖的老项目 | 绝大多数现代项目 |
开发中最常见的报错是TS2307: Cannot find module，遇到时可以按下面的思路排查。首先确认moduleResolution是否为node，如果项目里用了npm包但策略是Classic，那必然找不到。其次检查tsconfig中files、include、exclude配置是否把目标文件排除在编译范围外，被排除的文件即使存在也不会参与解析。再次，如果项目使用了路径别名，比如把@指向src目录，必须配合baseUrl和paths一起配置：
{
"compilerOptions": {
"baseUrl": "./",
"paths": {
"@/*": ["src/*"]
},
"moduleResolution": "node"
}
}
paths配置只是让编译器理解别名，运行时还需要打包工具（如webpack的resolve.alias）做同样的映射，两边的别名规则必须一致，否则会出现编译通过但运行时报模块找不到的怪异现象。
另外还有一类容易混淆的问题：第三方包没有任何类型声明文件，NodeJs策略会继续查找@types作用域下的同名包，如果也不存在，编译器就会报错。这时可以在项目根目录放一个声明文件，用模块声明语法兜底：
// types/global.d.ts declare module "some-untyped-package";
这样编译器会把这个包当作any类型处理，报错随之消失。当然这只是权宜之计，更好的方案是给社区贡献类型声明，或者用工具从JSDoc注释生成声明文件。
新版本解析选项的演进建议
TypeScript从4.7版本开始引入了node16和nodenext这两个解析策略，用于配合Node.js原生的ES模块支持。它们的区别在于：node16会根据最近package.json中的type字段动态决定按CommonJS还是ESM规则解析，而nodenext固定按ESM规则执行。如果你的项目使用import语法且在Node中直接运行，扩展名和导入路径的书写要求会更加严格，比如相对导入必须带完整扩展名。
对于一般的前端工程，如果代码最终交给webpack、Vite等打包器处理，moduleResolution保持为node（或新版本的bundler选项）即可满足需求。如果是Node后端项目且启用了ESM，则应该选择node16或nodenext。选择的核心原则只有一条：让编译期的解析规则尽可能贴近运行时的加载规则，两边规则一致了，模块解析相关的坑自然就少了。
TypeScript模块解析ClassicNodeJstsconfig配置修改时间：2026-09-13 22:55:00