npm依赖报错关键在于三类原因：权限问题（如EACCES、EPERM），应避免sudo，改用用户目录配置；网络/源问题（如ETIMEDOUT、ENOTFOUND），优先检查并切换镜像源；依赖冲突（如ERESOLVE），由npm 7+严格解析引发，可用--legacy-peer-deps临时绕过。
记 npm 依赖报错，关键不是死背错误信息，而是理解报错背后的三类常见原因：权限问题、网络/源问题、依赖关系冲突。掌握这三类的典型表现和对应动作，比硬记错误字符串高效得多。
权限类报错（如 EACCES、EPERM）
这类错误通常出现在全局安装或写入 node_modules 时，系统拒绝写入权限。
- 看到 EACCES: permission denied 或 EPERM: operation not permitted，优先检查是否用了
sudo npm install—— 这是反模式，应避免 - 正确做法：重置 npm 默认目录到用户主目录下（
mkdir ~/.npm-global && npm config set prefix '~/.npm-global'），再把~/.npm-global/bin加进$PATH - Windows 用户遇到类似问题，大概率是终端没以管理员身份运行，但更推荐用
nvm-windows或直接改 npm 配置而非提权
网络与源类报错（如 ETIMEDOUT、ENOTFOUND、EAI_AGAIN）
本质是 npm CLI 拿不到包信息或下载失败，和镜像源、代理、DNS 强相关。
-
ETIMEDOUT / EAI_AGAIN：网络超时，先执行
npm config get registry看当前源，国内建议切为淘宝源：npm config set registry https://registry.npmmirror.com -
ENOTFOUND registry.npmjs.org：DNS 解析失败，可临时换 DNS（如 8.8.8.8）或加
--no-registry测试是否源本身问题 - 公司环境常因代理报错，用
npm config get proxy和npm config get https-proxy查看，不需要时记得npm config delete proxy清理
依赖冲突类报错（如 ERESOLVE、ERESOLVED、peer dep conflict）
npm 7+ 默认启用严格依赖解析，遇到版本不兼容会直接中断，不再静默降级。
- ERESOLVE unable to resolve dependency tree：当前项目依赖与子依赖要求的 peer 版本不一致，例如 React 18 项目里某个 UI 库只支持 React 17
- 快速定位：加
--loglevel verbose重跑 install，看哪一行提示了冲突的包名和期望版本 - 解决方向有三：升级/降级冲突包（
npm install xxx@version）、用--legacy-peer-deps临时跳过校验（仅调试用）、或加--force强制覆盖（慎用，可能引发运行时问题）
其他高频信号词速查
不用记整句，盯住关键词就能快速归类：
-
missing script → package.json 里 scripts 字段没定义该命令，比如敲
npm run build却没写"build": "..." - Circular dependency → 模块 A require B，B 又 require A，一般不影响运行，但 webpack/vite 构建时会警告
- Cannot find module 'xxx' → 本地没装、拼写错、或装在了 devDependencies 里却在生产代码中引用（注意 NODE_ENV=production 下只加载 dependencies）
不复杂但容易忽略：每次遇到新报错，复制前 20 个字符去 npm 官方文档或 GitHub issues 搜一下，90% 的问题早有标准解法。真正要记的，是“权限→源→依赖”这个排查顺序。
