Cannot find module 报错怎么解决？6 个常见原因（路径 / 大小写 / 依赖没装）

Cannot find module 'xxx' 或 Module not found: Can't resolve 'xxx'，先看报错里的模块名是第三方包（如 react、axios）还是你自己的文件（如 ./utils、@/components/Button）——这一步直接分出两个完全不同的方向。

• 是第三方包 → 多半没装或装错位置（见 ①⑤）
• 是自己的文件 → 多半路径、大小写或 alias 问题（见 ②③④⑥）

① 第三方依赖没装（最常见）

成因：package.json 里没有这个包，或克隆项目后没 npm install。

修复：

npm install                # 先把已声明的依赖装全
npm install <包名>          # 缺哪个装哪个

② import 路径写错（相对路径层级）

成因：./ 和 ../ 数错层级，或漏写文件名。./utils 找的是当前目录，../utils 是上一级。

修复：对照真实目录结构数清层级；指向文件夹时确认里面有 index.ts，否则要写到具体文件。

③ 大小写不一致（本地能跑、CI 报错）

成因：macOS / Windows 不区分大小写，import './Button' 能找到 button.tsx；Linux（CI、Vercel）区分，直接 Can't resolve。

修复：让 import 的大小写和真实文件名完全一致。这条本地几乎不报，部署才炸，要专门检查。

④ tsconfig / 打包器 alias（@/ 路径）没配

成因：用了 @/components/... 这种别名，但 tsconfig.json 的 paths 或打包器 alias 没配（或配了 tsconfig 没配打包器）。

修复：在 tsconfig.json 配：

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./*"] } } }

非 Next.js 项目还要在打包器（Vite / webpack）里配同样的 alias，两边要一致。

⑤ 依赖装在了 devDependencies（生产找不到）

成因：运行/构建需要的包被 --save-dev 装进 devDependencies，生产环境 npm ci --omit=dev 装不到。

修复：

npm install <包名> --save     # 移到 dependencies

⑥ node_modules 损坏或没装全

成因：安装中断、网络问题、或切换分支后依赖对不上，导致部分模块缺失。

修复：删掉重装（保留 lockfile）：

rm -rf node_modules && npm install

快速定位顺序

1. 看模块名是包还是自己的文件。
2. 是包：npm ls <包名> 确认装没装、npm install。
3. 是文件：核对路径层级 → 大小写 → alias 配置。
4. 都对还报，删 node_modules 重装。

让 Codex 辅助

这是我的报错：Cannot find module 'xxx'（贴完整报错和这一行 import）。
请判断 xxx 是第三方包还是我项目里的文件，给出对应的定位步骤；
涉及改 tsconfig 或重装依赖的，先说明会改动什么。

风险提醒

• 删 node_modules 可以，别顺手删 package-lock.json，锁文件保证依赖可复现。
• 别为了"消报错"乱装同名但不对的包，先确认包名拼写。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关报错排查

同一套排查思路的常见报错，建议一起看：

• npm install 报错怎么解决
• npm run dev 能跑但 build 失败
• Node 版本不匹配怎么解决

免责声明

本文成因与修复对应 Node / TypeScript / 打包器的通用模块解析行为，供学习和排查参考；具体项目涉及客户代码时需明确授权并人工复核。