如何调试JavaScript运行时Cannot find module MODULE_NOT_FOUND报错

1. 可用于调试该类问题的工具 #

• Node.js 内置模块调试能力：无需额外安装依赖，通过环境变量开启即可打印完整模块查找日志
• TypeScript 编译器自带的解析追踪能力：可输出编译阶段所有模块的查找、匹配完整路径
• 编译产物静态检查：直接查看dist目录下编译生成的JS文件中的require/import路径，和实际目录结构做人工比对
• 路径映射处理工具自带的校验能力：比如tsc-alias、tsconfig-paths等路径处理工具提供的路径匹配检查命令

2. 编译阶段正常识别模块但运行时找不到的核心原因 #

根本原因是TypeScript 默认不会转译重写你写的模块导入路径：
你的tsconfig中配置了"baseUrl": "src"，TS在编译阶段做模块解析时，会自动将所有非相对路径开头的导入（比如你代码里写的import bar from 'server/foo/bar'），以src目录为根路径查找，也就是定位到src/server/foo/bar文件，只要文件存在TS就不会报错。
但TS完成语法转译输出JS文件时，会原样保留你写的server/foo/bar导入路径，不会把它转换成Node运行时能识别的相对路径（比如../foo/bar）。Node.js运行CommonJS模块时，完全不识别tsconfig里的baseUrl配置，遇到这种既不是.//../开头的相对路径、也不是内置模块/node_modules里的第三方包的导入字符串，会默认按第三方包的查找规则遍历各级node_modules目录查找对应模块，自然找不到你项目里的源码文件，最终抛出MODULE_NOT_FOUND错误。
补充：哪怕你在tsconfig里配置了paths路径别名，tsc默认输出时也不会重写路径，这个是TS的设计行为，不是bug。

3. 获取Node.js模块查找路径、定位问题的具体方法 #

• 开启Node模块调试日志：启动服务时注入NODE_DEBUG=module环境变量，即可打印Node运行时每一个模块的全部查找路径：
  • Linux/macOS 执行：NODE_DEBUG=module node dist/server/index.js
  • Windows CMD 执行：set NODE_DEBUG=module && node dist/server/index.js
  • Windows PowerShell 执行：$env:NODE_DEBUG=module; node dist/server/index.js
    执行后控制台会逐行输出Node尝试加载server/foo/bar时遍历的所有文件路径，你可以直接看到Node根本没有进入dist目录查找源码文件，而是在各级node_modules目录下匹配目标模块。
• 对比TS编译阶段的模块解析路径：执行npx tsc --traceResolution > ts-resolve.log，会把TS编译时查找所有模块的完整路径输出到日志文件中，你可以看到TS定位server/foo/bar的路径是项目根目录/src/server/foo/bar，和Node运行时的查找路径完全不匹配，即可实锤是路径未重写的问题。
• 快速校验编译产物：直接打开dist/server/index.js文件，搜索server/foo/bar字符串，只要看到require语句里的路径仍然是不带相对前缀的server/foo/bar，就可以直接确认问题根因。
• 可选修复方案参考：
  • 最无依赖方案：将所有非相对路径的导入改成相对路径写法，比如import bar from '../foo/bar'，Node原生支持，不需要额外工具处理
  • 编译后替换路径方案：保留现有非相对导入写法，tsc编译完成后执行npx tsc-alias，自动将编译产物里的非相对路径替换为正确的相对路径，之后再启动Node服务即可
  • 运行时解析方案：启动Node时挂载tsconfig路径解析钩子，执行node -r tsconfig-paths/register dist/server/index.js，让Node运行时按照tsconfig的baseUrl/paths配置查找模块，适合开发环境使用

内容的提问来源于stack exchange，提问作者BlueSialia