背景与动机 在大型单体仓(monorepo)中,随着项目的演进和多人协作,依赖很容易累积成一座"依赖垃圾场"。安装变慢、CVE 警告频繁、CI 时间拉长、维护成本上升,都是常见痛点。在一次对约 500 个依赖的 Nx monorepo 例行检查中,最终安全去除了约 120 个未使用的包,安装时间在本地和 CI 中各自缩短了大约一分钟,安全告警明显减少,团队体验得到提升。下面把过程、工具选择、验证策略和实战建议系统化,便于在你自己的仓库中复用。 工具选择:为什么用 Knip 而不是 Depcheck 传统上很多人会想到 depcheck,但它对现代 monorepo、多层 workspace、工具链配置和类型仅引用的场景支持有限。Knip 是一个更现代、对 monorepo 友好的选择,它会解析入口点、常见栈的配置引用,并构建依赖图来找出可能的未使用依赖。
depcheck 的仓库状态已经比较安静,而 Knip 在社区推荐列表中出现频率更高,能够作为第一轮自动检测的信号源。 扫描与基线验证 任何自动化检测都只是线索,不应直接成为删除依赖的唯一依据。先做基线扫描,记录现状:使用 yarn dlx knip 在工作区根目录运行一次全量扫描,生成未使用依赖列表并保存快照。并在删除前做一遍构建和测试流程,确保能在出问题时回退到有依赖的状态。 逐个验证的原则 对 Knip 的结果采取"先删后验"的策略。把它标记为提示列表,而不是判决单。
对每一项建议删除的包,先从 package.json 中卸载或在子工作区中移除,然后运行 CI 中常用的流水线步骤:构建、测试、lint、e2e、代码生成/类型生成,再本地跑一次开发服务器进行冒烟测试。如果任一环节失败,说明该依赖是被间接使用的,需要恢复并记录原因。很多误报源自几类常见场景:配置文件中以字符串引用的 preset 或 runner、只在 npm script 或 CI 中调用的 CLI、通过插件发现机制动态加载的模块、类型信息或工具链仅在构建时使用的包。 ignore 列表与可审计注释 在实践中建立一个可维护的 Knip 忽略列表非常重要。把那些确实被间接使用但被静态分析工具误判的包列入忽略,并用简短注释说明为什么保留。例如明确写出"在 jest 配置中以字符串引用""仅在 CI 脚本中调用""通过某插件机制按名称加载"等理由。
把这些注释与团队共享,放在仓库里方便将来审查。随着时间推移,忽略列表也需要周期性复查以避免"永久遗留"的依赖。 常见的误报类型与识别方法 有几类误报需要特别留心。第一类是配置字符串引用,比如 Jest 的 preset 名称或 test runner 名称,静态解析器无法把字符串当作依赖引用识别。第二类是脚本中调用的 CLI 工具,它们只在 package.json 的 scripts 或 CI 配置中出现。第三类是插件发现或反射式加载,例如某些框架会按约定名称去 require 一个插件包。
第四类是类型仅引用(type-only),TypeScript 在 emit 阶段可能不保留某些引用,静态扫描可能判断为未使用。第五类是构建工具或运行时外部注入的依赖,比如某些 bundler 在配置中以路径或别名引用。识别这些误报的办法是结合 grep、build 输出和运行时日志,必要时在本地模拟 CI 环境去触发可能的路径。 实操命令与流程建议 在移除包时保持可重复和可回滚非常关键。建议的步骤包括先在 feature 分支上做变更,运行 yarn install、yarn nx affected -t build test lint 或仓库的等效流水线,然后在本地用 yarn nx run <app>:serve 或对应的 dev 命令做冒烟测试。把所有变更放入小而清晰的 PR,附上测试截图或 CI 通过的证明,并在合并时选择在较安静的时段进行,便于快速回滚。
预览部署(preview deploy)是非常有价值的一步,通过在临时环境中点击几条关键用户路径来捕捉运行时缺失资源或错误。 版本控制与回退策略 批量删除依赖会产生较多变更,但小而频繁的提交更易审查。如果决定批量处理,尽量在合并后保持短时间监控窗口:合并到主分支后不要立刻触发大规模发布,先观察一两个小时或一个工作日的日志和用户反馈以防问题。把恢复依赖的操作和理由记录在 PR 或 issue 中,确保恢复步骤可复制。 对 CI 的影响与优化 删除依赖后,yarn install 的时间和安装数据量都会下降,这直接影响 CI 运行时长。除了即时收获,还可以把 Knip 集成进 CI 做一轮"报告式"检测:先让 Knip 在非强制模式下运行若干个 sprint, 收集并调整忽略规则。
当团队对误报情况熟悉并信任漏报率后,可以考虑把新出现的未使用依赖视为失败条件,从而防止新的冗余依赖被引入。 额外收益:减少安全告警与维护负担 减少依赖不仅带来体积和速度的优势,还能显著降低面临的安全告警数量。每减少一个包,就减少了一组潜在的 CVE 告警、版本冲突和转译工具链复杂度,长期看能节省开发者在依赖更新和安全审查上的时间。 如何在团队内推行这套流程 要把这种清理惯例推到团队里,需要一些组织层面的工作。首先,把检测工具的报告和删除流程写成文档,清晰说明什么情况需要人工复核、如何做回退、忽略条目的书写规范。其次,设定试运行期:把 Knip 作为"观察型"工具在 CI 中运行一个 sprint,收集团队反馈,对 ignore 列表调整一轮。
最后,把成功案例共享给团队,包括显著节省的 CI 时间和减少的安全告警,用数据来说话更能说服团队接受新的流程。 注意事项与陷阱 不要对自动检测盲目执法,任何自动化都可能漏判或误判。删除依赖前应优先在本地或可控环境中验证关键路径。对关键的生产服务和公共包(比如团队共享的 eslint-config)要格外小心,确保忽略配置覆盖到这些工作区。另一个常见陷阱是仅看单次构建通过就合并,建议至少在多个分支或不同环境中跑一轮完整的测试集。 拓展应用:清理未使用文件与类型 像 Knip 这样的工具有时也能发现未使用的文件、枚举或类型声明。
对于死代码审计,遵循相同原则:工具给出提示,人工验证关键路径,再做安全删除。逐步释放这些冗余代码可以让代码库更简洁,也能降低新成员上手成本。 实际成效回顾 在本文提到的例子中,仓库从大约 510 个唯一包缩减到约 390 个,净减少约 120 个包。安装时间在本地和 CI 中各自减少约一分钟,团队收到的安全警告显著减少,且没有重大发布事故。这是典型的低风险、高回报的技术债清理工作。 总结与行动建议 清理 monorepo 中的未使用依赖并不是一次性工作,而是可以成为持续维护流程的一部分。
将 Knip 或类似工具作为信号源,结合手工验证的"删 - 验 - 回退"循环,用可审计的忽略列表记录遇到的特殊情况,并逐步把检测纳入 CI 报告中,这样既能减少体积和安全噪音,又能保持开发体验和稳定性。小心谨慎地做变更、保持团队透明和可回滚的步骤,是确保清理工作不会扰乱开发节奏的关键。希望这些实用建议能帮助你在自己的 Nx monorepo 中稳妥地清理出可观的空间与时间收益。 。
