Module not found 报错

一句话：代码里 import/require 的模块，运行时找不到，通常是没装、路径写错、大小写不对，或 ESM/CommonJS 混用。

它是什么

Node.js/前端项目最常见的报错之一。本质是"引用的东西运行时找不到"：可能是这个 npm 包根本没装，可能是本地文件路径写错，也可能是模块系统不匹配（比如用 require 导入一个只支持 ESM 的包）。

适合干什么

• 刚 clone 下来的项目跑不起来
• 换了目录结构后突然报错
• 升级依赖后项目跑不起来

不适合干什么

• 模块存在但报权限错误（那是权限问题，不是这个）

普通人怎么用

先看报错里到底是哪个模块名找不到：①是不是忘了 npm install；②路径是不是打错字或大小写不对（Mac/Linux 对大小写敏感，Windows 不敏感，本地能跑、部署到 Linux 服务器报错，十有八九是这个）；③是不是用了相对路径但当前工作目录不对。

进阶用户怎么用

区分是"包没装"还是"ESM/CommonJS 混用"——后者要么升级 Node 版本改用动态 import()，要么找这个包的 CommonJS 版本；monorepo 项目还要注意软链接（symlink）没正确指向的情况。

常见误区

• 以为删了 node_modules 重装一定能解决，其实很多时候是路径/大小写问题，重装没用
• 以为报错的模块名就是缺的那个包，实际经常是它的某个子依赖缺失

和相似工具的区别

• 和 TypeScript 的 "Cannot find name" 不是一回事：那是类型系统层面的报错，这个是运行时真的找不到文件/包

入门步骤

• 复制完整报错栈，尤其是 Require stack 那几行
• 打开 package.json 确认这个包名是否真的在依赖列表里
• rm -rf node_modules package-lock.json 后重新 npm install