关键在于理解依赖树结构、版本决策机制与错误根源：用npm ls定位包来源和幽灵依赖，--save-exact或save-exact=true锁定版本，npm link实现本地实时调试，npm explain和resolutions精准排查修复ERESOLVE冲突。
掌握 JS 中 npm 依赖的常见陷阱与调试技巧，关键不是背命令，而是理解“依赖树怎么长、谁在决定版本、错误从哪冒出来”。下面这几个实操性强的切入点，能帮你快速建立判断力和修复路径。
看清依赖树：用 npm ls 定位真实来源
很多报错（比如 Cannot find module 'lodash' 或 peer dep missing）表面是缺包，实际是版本错位或幽灵依赖。直接运行：
-
npm ls lodash—— 查看 lodash 被哪些包拉进来、用了哪个版本 -
npm ls --all | grep -A 5 -B 5 "axios@1.6"—— 快速定位某版本出现在哪一层 -
npm ls --depth=0—— 只看顶层显式声明的依赖，对比 package.json 是否一致
注意：如果某个包只出现在深层子依赖里，但你代码里直接用了它，那就是幽灵依赖——它随时可能消失，必须补到 dependencies 中。
锁定版本：避免“装得通，跑不通”
默认 npm install lodash 会装 ^4.17.21 这类语义化版本，下次安装可能升级到 4.18.0，而这个小版本恰好改了某个 API 行为。解决办法很直接：
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
- 安装时加
--save-exact：npm install lodash@4.17.21 --save-exact，package.json 里写死"lodash": "4.17.21" - 全局设为默认：
npm config set save-exact true，之后所有 install 都自动精确锁定 - 配合
package-lock.json提交到 Git —— 它才是团队环境一致的真正依据，不是 node_modules
本地调试不发包：npm link 实时联动
开发一个工具库（比如 @myorg/utils），改一行代码就要 npm publish → npm install 太慢。用 npm link 建立软链：
- 进工具库目录：
npm link（创建全局链接） - 进主项目目录：
npm link @myorg/utils（把全局链接映射进当前 node_modules） - 改工具库源码 → 主项目立即生效，无需重装
⚠️ 注意：link 后 package.json 中的版本号会被忽略，变成符号链接。上线前务必 npm unlink @myorg/utils 并重新 npm install，否则 CI 环境找不到链接目标。
排查 ERESOLVE 冲突：别急着加 --legacy-peer-deps
npm 7+ 默认严格校验 peerDependencies，报错 ERESOLVE unable to resolve dependency tree 时，先别跳过检查：
- 用
npm explain xxx（如npm explain react）直接看到哪个包要求react@17，哪个又要求react@18 - 查
npm ls xxx --all看冲突包是否来自已废弃的工具（比如@webpack-cli/init在 v5+ 已内置，删掉就解了） - 真要收敛，用
resolutions字段（需搭配 yarn 或 npm >= 8.3 +overrides）强制指定统一版本，而不是降级校验逻辑
不复杂但容易忽略。
