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