Node.js 报 "Cannot find module" 错误怎么解决？
Cannot find module 的排查顺序：检查路径与文件名大小写 → 相对路径是否带 ./ → 包是否真的装了（npm install）→ node_modules 损坏则删了重装 → ESM 需写扩展名。本文给出完整排查清单。
这个错误 = Node 按你给的路径找不到模块。按下面清单从上往下查，优先检查路径、安装与实际运行环境，不保证固定覆盖率。
排查清单
1. 路径和文件名写对了吗
const myModule = require('./path/to/myModule'); // 相对路径必须带 ./
- 相对路径忘记写
./是最常见错误——不带./会被当成 npm 包名去 node_modules 找； - 大小写敏感：由实际文件系统决定，macOS/Windows也可使用大小写敏感配置，不应只按操作系统判断。
./Utils.jsvs./utils.js是经典部署事故。
2. 包真的安装了吗
npm install some-package # 确认装过
npm list some-package # 验证安装结果
克隆的项目先跑 npm install；CI 上要用 npm ci。
3. node_modules 损坏：删了重装
包安装一半被中断、npm 缓存损坏时：
npm ci # 有有效锁文件时按锁文件重新安装
4. ESM 的特殊规则
"type": "module" 或 .mjs 文件里，Node的相对/绝对文件路径import通常必须写扩展名（包名导入由exports等规则解析）：
import { add } from './math.js'; // ✅
import { add } from './math'; // ❌ ERR_MODULE_NOT_FOUND
5. 其他高频原因
- CommonJS可受NODE_PATH影响；原生ESM不依赖它查找包；
- TypeScript 编译产物路径和源码对不上（检查
outDir/rootDir）； - 包有
exports字段限制，深层路径不可导入（通常是ERR_PACKAGE_PATH_NOT_EXPORTED，需与缺文件错误区分）； - Docker 里 COPY 漏了文件，或 .dockerignore 排除了源码。
快速定位法
报错信息里有完整路径，先打印确认：
console.log(require.resolve('./myModule')); // 解析成功会打印绝对路径，失败即复现错误
常见问题（FAQ）
Q：本地好好的，部署就报这个错？
大概率是大小写问题或 .dockerignore 漏拷文件。Linux 文件系统区分大小写是头号嫌犯。
Q：装的是 @types 开头的类型包还报错？
@types/* 只提供类型声明，不含运行时代码。运行时还需要装包本体。
Q：pnpm 项目报这个错？
pnpm 的依赖隔离更严格，间接依赖不能直接 require。把用到的包显式加进 dependencies。
