npm 提供了多种诊断和调试工具，帮助开发者解决包管理相关的问题。掌握这些工具可以显著提高问题排查效率。
npm 诊断命令
npm doctor
npm doctor 检查 npm 环境的健康状况，识别潜在问题。
# 运行诊断 npm doctor # 检查特定方面 npm doctor --registry npm doctor --network npm doctor --permissions
输出示例：
npm ERR! code ENOENT npm ERR! syscall open npm ERR! path /Users/user/.npm/_cacache/index-v5/ npm ERR! errno -2 npm ERR! enoent ENOENT: no such file or directory
npm config diagnose
诊断配置问题：
# 查看配置 npm config list # 查看特定配置 npm config get registry # 查看配置文件位置 npm config get userconfig npm config get globalconfig npm config get projectconfig
常见问题诊断
1. 安装失败
问题：网络问题
# 检查网络连接 ping registry.npmjs.org # 检查代理设置 npm config get proxy npm config get https-proxy # 使用镜像 npm config set registry https://registry.npmmirror.com
问题：权限问题
# 检查权限 ls -la ~/.npm # 修复权限 sudo chown -R $(whoami) ~/.npm # 使用 npm config 设置用户 npm config set user $(whoami)
问题：缓存问题
# 清理缓存 npm cache clean --force # 验证缓存 npm cache verify # 重新安装 rm -rf node_modules package-lock.json npm install
2. 依赖冲突
问题：peer 依赖冲突
# 查看依赖树 npm ls # 查看特定包的依赖 npm ls <package> # 使用严格模式 npm config set strict-peer-deps true # 强制安装 npm install --force
问题：版本冲突
# 查看过期的包 npm outdated # 更新包 npm update # 使用 overrides npm config set overrides '{"package": "1.2.3"}'
3. 锁文件问题
问题：package-lock.json 损坏
# 删除锁文件 rm package-lock.json # 重新安装 npm install # 使用 npm ci npm ci
问题：锁文件不一致
# 查看差异 npm diff # 重新生成锁文件 rm package-lock.json npm install
4. 脚本执行问题
问题：脚本找不到
# 查看所有脚本 npm run # 检查脚本语法 cat package.json | grep scripts # 使用完整路径 npm run /path/to/script.js
问题：环境变量问题
# 查看环境变量 npm run <script> --verbose # 设置环境变量 export NODE_ENV=production npm run build # 在脚本中使用环境变量
高级诊断工具
1. npm explain
解释包为什么被安装：
# 解释包的安装原因 npm explain <package> # 查看依赖树 npm explain <package> --json
输出示例：
express@4.18.2 node_modules/express express@"^4.18.0" from the root project
2. npm query
查询依赖信息：
# 查询所有过期的包 npm query ":outdated" # 查询所有开发依赖 npm query ":dev" # 查询特定包的依赖 npm query "lodash > *" # 查询依赖路径 npm query "#./packages/*"
3. npm diff
比较依赖版本：
# 比较当前安装与 package.json npm diff # 比较特定包 npm diff <package> # 比较两个版本 npm diff <package>@1.0.0 <package>@2.0.0
4. npm ls
查看已安装的包：
# 查看所有包 npm ls # 查看顶级依赖 npm ls --depth=0 # 查看特定包 npm ls <package> # 以 JSON 格式输出 npm ls --json # 查看全局包 npm ls --global
调试技巧
1. 启用详细日志
# 设置日志级别 npm config set loglevel verbose # 运行命令 npm install --verbose # 设置为调试级别 npm config set loglevel silly
2. 使用调试标志
# 启用调试 npm install --dd # 启用详细调试 npm install --ddd # 查看网络请求 npm install --loglevel=http
3. 查看安装日志
# 查看日志文件 cat ~/.npm/_logs/*.log # 查看最新日志 tail -f ~/.npm/_logs/*.log # 搜索错误 grep -i error ~/.npm/_logs/*.log
4. 使用 npm debug
# 启用调试模式 DEBUG=* npm install # 启用特定模块的调试 DEBUG=npm:* npm install # 启用网络调试 DEBUG=npm:request npm install
性能诊断
1. 安装速度慢
# 检查网络速度 ping registry.npmjs.org # 使用镜像 npm config set registry https://registry.npmmirror.com # 增加并行度 npm config set maxsockets 50 npm config set network-concurrency 16 # 使用缓存 npm install --prefer-offline
2. 磁盘空间问题
# 查看磁盘使用 du -sh ~/.npm du -sh node_modules # 清理缓存 npm cache clean --force # 使用 pnpm 节省空间 npm install -g pnpm
3. 内存问题
# 增加内存限制 export NODE_OPTIONS="--max-old-space-size=4096" # 使用 npm ci npm ci # 分批安装 npm install --no-package-lock
安全诊断
1. 安全漏洞
# 运行安全审计 npm audit # 查看漏洞详情 npm audit --json # 修复漏洞 npm audit fix # 强制修复 npm audit fix --force
2. 供应链安全
# 查看包的完整性 npm view <package> integrity # 检查包的来源 npm view <package> repository # 查看包的维护者 npm view <package> maintainers
3. 许可证问题
# 检查许可证 npm install -g license-checker license-checker # 查看特定包的许可证 npm view <package> license
工具和插件
1. npm-check-updates
检查依赖更新：
# 安装 npm install -g npm-check-updates # 检查更新 ncu # 更新 package.json ncu -u
2. npm-check
检查包的状态：
# 安装 npm install -g npm-check # 检查包 npm-check # 交互式更新 npm-check -u
3. depcheck
检查未使用的依赖：
# 安装 npm install -g depcheck # 检查未使用的依赖 depcheck # 忽略特定包 depcheck --ignore-missing=package-name
4. npm-why
解释包的安装原因：
# 安装 npm install -g npm-why # 查询包 npm-why <package>
故障排除流程
1. 通用故障排除流程
# 1. 清理缓存 npm cache clean --force # 2. 删除 node_modules rm -rf node_modules # 3. 删除锁文件 rm package-lock.json # 4. 重新安装 npm install # 5. 如果仍然失败，使用详细日志 npm install --verbose
2. 特定问题流程
安装失败
# 1. 检查网络 ping registry.npmjs.org # 2. 检查代理 npm config get proxy # 3. 使用镜像 npm config set registry https://registry.npmmirror.com # 4. 重新安装 npm install
依赖冲突
# 1. 查看依赖树 npm ls # 2. 查看过期的包 npm outdated # 3. 更新包 npm update # 4. 使用 overrides npm config set overrides '{"package": "1.2.3"}'
脚本失败
# 1. 查看脚本 npm run # 2. 检查语法 cat package.json | grep scripts # 3. 手动运行脚本 node /path/to/script.js # 4. 查看环境变量 npm run <script> --verbose
最佳实践
1. 定期诊断
# 每周运行一次 npm doctor npm audit npm outdated
2. 保存诊断信息
# 保存诊断结果 npm doctor > npm-doctor.log npm audit > npm-audit.log npm outdated > npm-outdated.log
3. 使用版本控制
# 提交 package-lock.json git add package-lock.json git commit -m "Update lock file" # 回滚到之前的版本 git checkout HEAD~1 package-lock.json
4. 文档化问题
在项目中创建 TROUBLESHOOTING.md：
# Troubleshooting ## Common Issues ### Installation Fails ```bash npm cache clean --force rm -rf node_modules package-lock.json npm install
Dependency Conflicts
npm ls npm update
掌握 npm 诊断和调试工具可以显著提高问题排查效率，减少开发中的停顿时间。