JavaScript / TypeScript / 系统课时
排查模块解析失败
排查模块解析失败
模块解析失败看起来都是“找不到模块”,但根因可能位于导入路径、包导出、解析模式或声明文件。本文给出一条从错误现象到验证结果的排查顺序,目标是先确认失败发生在哪一层,再做最小修复。
学习目标
- 区分 TypeScript 编译期模块解析失败与 Node.js 运行期加载失败
- 按路径、包导出、解析模式和声明文件的顺序定位问题
- 使用编译器解析跟踪验证模块最终解析到的文件
先判断失败发生在哪一层
编译器报 TS2307: Cannot find module ...,说明 TypeScript 没有为当前导入找到可接受的源码或类型声明;程序已经编译,却在 Node.js 启动时出现 ERR_MODULE_NOT_FOUND,则是运行时加载规则没有找到目标。两类错误可能来自同一条 import,但验证工具和修复位置不同。
最先记录三项信息:报错的完整导入字符串、当前文件路径、项目实际使用的 tsconfig.json。在 monorepo、测试工具或 IDE 中,最常见的误判之一就是以为正在读取某份配置,实际使用了另一份配置。
按解析链路逐层排查
先检查相对路径是否真的存在,并核对文件名大小写。Windows 和默认 macOS 文件系统可能让 ./User 与 ./user 暂时可用,部署到区分大小写的 Linux 后才失败。若项目使用 ESM 与 Node16/NodeNext 解析,源码中的相对导入还要符合 Node.js 的运行时规则,常见写法是导入 ./user.js,由 TypeScript 在编译期映射到对应的 .ts 源文件。
非相对导入再检查包是否安装,以及 package.json 的 exports 是否允许当前子路径。存在 exports 时,pkg/internal 并不会因为磁盘上有这个文件就自动成为合法入口;包必须显式导出对应路径。随后确认 module 与 moduleResolution 是否与实际运行方式一致,例如 Node ESM 项目优先使用配套的 Node 解析模式,交给打包器处理模块的前端项目通常使用面向 bundler 的解析模式。
最后检查类型声明。JavaScript 文件能在运行时被加载,不代表 TypeScript 一定能找到类型。包应提供 .d.ts,或通过 types、exports 的 types 条件暴露声明。第三方库没有内置声明时,再确认是否存在匹配版本的 @types/*。skipLibCheck 只能跳过声明文件内部的类型检查,不能把缺失的声明文件“变出来”。

用解析跟踪确认编译器实际做了什么
当目录结构看起来正确却仍然报错时,不要继续猜。TypeScript 的 --traceResolution 会打印每个模块候选、读取的 package.json、命中的 exports 条件以及最终解析结果。下面的命令把完整跟踪保存到文件,便于搜索目标模块。
npx tsc --noEmit --traceResolution > resolution-trace.txt 2>&1预期结果:项目存在解析错误时,命令可能返回非零退出码,但 resolution-trace.txt 会被创建,其中可以搜索报错模块名。成功解析的条目会显示最终命中的文件路径,实际路径会因项目而不同。
======== Module name '<MODULE>' was successfully resolved to '<PATH>'. ========如果跟踪中从未访问你预期的目录,优先回查 baseUrl、paths、工作目录和实际生效的 tsconfig.json;如果已经找到 JavaScript 文件却仍提示缺少声明,就把注意力转到 .d.ts、types 与包的导出条件。
修复后做最小验证
修复解析问题后先只做类型检查,不要立即混入测试、打包和启动流程。这样能证明问题已经从 TypeScript 的解析阶段消失。
npx tsc --noEmit && echo "TYPECHECK_OK"预期输出
TYPECHECK_OK如果类型检查通过但运行时仍然报 ERR_MODULE_NOT_FOUND,说明编译期和运行期规则仍不一致,应检查编译后的导入字符串、输出目录、package.json 的 type 以及 Node.js 实际执行的文件。模块解析排障的关键不是反复改扩展名,而是沿着“导入字符串 → 解析规则 → 包导出 → 类型声明 → 运行时加载”逐层确认事实。