依赖关系检查：为什么你的项目一升级就崩？

上周同事小李更新了 npm 包，本地跑得好好的，一上测试环境就报错：‘Module not found: Can't resolve 'lodash/fp'’。查了半天，发现是新版本的 utils-core 依赖了 lodash 的某个子模块，但项目里只装了主包，没装 lodash/fp —— 这就是典型的依赖关系没理清。

依赖关系检查，不是锦上添花，是保命操作

软件不是单个文件拼起来的，而是像搭积木：A 模块调用 B，B 又依赖 C 和 D，D 还悄悄用了 E 的某个 beta 版本……链条越长，越容易在某处断掉。依赖关系检查，就是定期摸一遍这些连接点，看看有没有漏装、版本打架、路径错乱、许可冲突这些问题。

常见翻车现场

• 版本不兼容：你升级了 React 18，但 UI 组件库只支持到 17.3，启动直接白屏；
• peer 依赖缺失：装了个自定义 Hook 库，它声明 peerDependencies: { react: "^17.0.0" }，可你装的是 18.x，npm 不会自动提醒，运行时才报错；
• 循环依赖：A.js require B.js，B.js 又 import A.js，开发时可能不显，打包后体积暴涨或执行顺序错乱；
• 幽灵依赖（phantom dependency）：代码里写了 require('chalk')，但 package.json 根本没写 chalk，靠的是另一个依赖顺带装进来的 —— 某天那个依赖升级删掉了 chalk，你的日志立刻变黑底白字。

怎么动手查？别光靠眼睛扫

命令行三板斧够日常用：

npm ls chalk

查看 chalk 在整个依赖树里的所有版本和位置；

npm ls --depth=0

只看顶层依赖，快速确认是否有多余包；

yarn why lodash

（Yarn 用户）查清楚 lodash 是谁拉进来的、为什么是这个版本。

更进一步，可以用 depcheck 扫未使用的依赖：

npx depcheck

它会告诉你哪些包在 package.json 里写着，但代码里根本没 import/require 过——这类包删掉不心疼，还能减小安装体积。

CI 里加一道卡

光靠人手动查，容易漏。建议在 GitHub Actions 或 GitLab CI 里加一步：

npm ls --fail-if-missing && npx depcheck --ignore-bin-package --ignores=webpack,eslint

只要依赖树有断裂或存在幽灵依赖，构建直接失败，逼着提交者先修好再合代码。

依赖关系检查不是炫技，是让每次 npm install 都心里有底。就像开车前看一眼胎压和油量——不费事，但能避开半路抛锚。