dependency-management

依赖管理

决定依赖哪些内容、保持依赖更新、响应安全公告并降低供应链风险。适用于各种技术栈的原则；具体做法因包管理器而异。

---

适用场景

• 为新项目或现有项目建立依赖卫生规范
• 响应安全公告
• 升级关键依赖的主版本
• 添加新依赖（评估、决策）
• 移除依赖（清理）
• 审计已安装的依赖及其实际使用情况
• 制定更新节奏和策略
• 诊断更新后构建失败的问题

不适用场景

• 一般代码审查（使用 code-review-web）
• 基础设施漏洞扫描（使用 security-baseline）
• 固定供应商或服务合同（使用 vendor-evaluation）
• 评估依赖对性能的影响（使用 performance-optimization）

---

必需输入

• 正在使用的包管理器和锁文件（npm、yarn、pnpm、pip、gem、composer 等）
• 当前依赖列表（生产和开发依赖）
• 当前安全公告（运行审计；查看 Snyk、Dependabot 等服务）
• 更新历史（关键依赖上次更新时间）
• 风险概况（生产环境关键程度、对变更的容忍度）

---

框架：依赖的 4 个类别

每个依赖都属于以下类别之一。类别决定相应策略。

类别 1：关键运行时依赖

在生产环境中运行，发生故障会导致系统出问题的代码。

示例：框架、数据库驱动、支付 SDK、身份验证库。

策略：

• **更新节奏：**每月更新次要版本，每季度更新主版本（需提前规划）
• **安全：**收到安全公告后 24-72 小时内修复，严重问题需在 24 小时内修复
• **版本固定：**固定到确切版本或使用狭窄的版本范围
• **审查：**采用前进行全面评估

类别 2：支持型运行时依赖

在生产环境中运行，但可替换或非关键的代码。

示例：工具库、格式化库、非核心集成。

策略：

• **更新节奏：**每月与关键依赖一起更新
• **安全：**收到安全公告后一周内修复
• **版本固定：**可接受狭窄的版本范围（例如 ^1.2.3）
• **审查：**适度评估；考虑其他替代方案

类别 3：开发/构建依赖

仅在开发或构建期间运行，不在生产环境中运行的代码。

示例：打包工具、代码检查工具、测试框架、类型检查器。

策略：

• **更新节奏：**每季度更新
• **安全：**一周内修复（仍然重要；供应链攻击会针对构建工具）
• **版本固定：**可接受版本范围
• **审查：**可从简；开发工具出问题会很快显现

类别 4：可选/仅个人开发使用的依赖

个别开发者使用、但不属于共享开发环境的工具。

通常不在项目层面管理。此处提及仅为完整起见。

---

框架：5 个风险维度

评估依赖时，请考虑以下因素：

维度 1：维护状况

• 上次提交日期（数月前的提交令人担忧）
• 未解决问题的数量和存续时间
• 维护者数量
• 赞助或商业支持
• 路线图是否清晰可见

一项已弃用一年的依赖，随时可能成为隐患。

维度 2：影响范围

• 包的大小
• 传递依赖的数量
• 在打包文件中的占用（适用于客户端）
• 所需权限（文件系统、网络等）

一个小型依赖如果引入了 50 个传递依赖，其影响范围就涵盖了这 50 个依赖。

维度 3：可替换性

• 移除它有多困难？
• 是否有替代方案？
• 能否自行实现相应功能？
• API 是否遵循标准或惯用做法？

无法替换的依赖，意味着你把筹码交给了它的维护者。

维度 4：可信度

• 维护者或组织的声誉
• 代码质量（浏览一下源代码）
• 许可证（GPL、MIT、BSD、专有许可证、无许可证）
• 安全问题历史
• 供应链实践（发布是否签名、发布账号是否启用双重身份验证）

维度 5：成本

• 评估、集成和维护所需的时间
• 破坏性变更的风险
• 锁文件熵
• 潜在的安全暴露风险
• 对包体积的影响（适用于客户端）

每个依赖项都有成本。免费包并非没有成本。

---

工作流

步骤 1：盘点

运行依赖项列表：

# npm/yarn/pnpm
npm ls --all --json

# pip
pip list

# gem  
bundle list

对每个顶层依赖项进行分类（关键／辅助／开发）。对于传递依赖，通常无需单独管理，除非其中某个出了问题。

步骤 2：审计

运行安全审计：

npm audit
yarn npm audit  # Yarn 2+; "yarn audit" on Yarn 1 Classic
pip-audit
bundle audit

针对每项发现：

• 严重程度（严重、高、中、低）
• 包和版本
• 是否有可用修复？
• 是直接依赖还是传递依赖？

步骤 3：分类并确定优先级

严重程度	直接依赖	间接依赖
严重	今天修复	本周修复（如果有修复方案；如果没有，则跟踪）
高	本周修复	本月修复
中	本月修复	跟踪；在下一轮修复
低	跟踪	跟踪

生产代码中的严重和高危问题属于紧急事项。低危和中危问题则按计划处理。

步骤 4：合并修复前进行测试

即使是补丁级更新也可能造成破坏。对于关键依赖项：

• 运行完整测试套件
• 在预发布环境进行冒烟测试
• 发布后密切关注监控

对于辅助依赖项和开发依赖项：

• 运行测试套件
• 测试失败时可以调查；不要合并已知有问题的更新

步骤 5：规划主要版本升级

主要版本会带来破坏性变更。应做好规划，而不是仓促升级。

对于每次主要版本升级：

• 阅读变更日志和迁移指南
• 估算迁移工作量
• 安排工作（不要在截止日期压力下进行）
• 创建分支并进行充分测试
• 如果是关键依赖项，则规划分阶段发布

不要无限期搁置主要版本升级。等待越久，升级就越困难。

步骤 6：制定策略

记录：

• 更新频率（例如，每月审查、每季度升级）
• 安全响应 SLA（例如，严重问题在 24h 内处理）
• 新增依赖项的审批流程（由谁批准）
• 移除标准（何时弃用某个依赖项）
• 锁定策略（精确版本、窄范围、宽范围）

策略能在团队人员变动后继续发挥作用。没有策略，依赖项管理就会变成混乱的临时工作。

步骤 7：自动化

• 使用 Renovate 或 Dependabot 自动创建更新 PR
• CI 在每个 PR 上运行审计
• 阻止合并存在严重安全公告的更新（为误报提供覆盖流程）
• 针对已安装的包，有安全公告时发送通知
• 在 PR 审查中检查锁文件差异

自动化能减少繁琐工作。手动检查无法扩展。

步骤 8：定期审计用法

每季度：

• 检查已安装但未在任何位置导入的依赖项（运行 depcheck 等工具）
• 检查落后的主要版本（落后超过 1-2 个主要版本时，需要制定升级计划）
• 检查无人维护的包（最后一次提交距今超过一年时，考虑替换）
• 审计许可证（条款是否有变更？）

移除未使用的依赖项。替换无人维护的依赖项。

---

新依赖项评估

添加新依赖项之前，请回答：

• 这能解决什么问题？
• 能否在不添加依赖项的情况下解决？（小问题通常可以。）
• 有哪些替代方案？
• 该包是否在积极维护？
• 安装体积和对包体积的影响如何？
• 有哪些传递依赖？（值得快速检查一下。）
• 许可证是什么？
• 安全记录如何？
• 替换它有多容易？

默认做法：不添加。只有当价值明显高于成本时才添加。成本包括持续维护，而不仅仅是安装。

---

移除依赖项

移除依赖项时：

• 找出所有用法（搜索代码库）
• 替换每处用法（使用原生代码、其他依赖项或空操作）
• 从 package.json 或等效文件中移除
• 更新锁文件（运行安装命令）
• 验证测试通过
• 验证构建体积有所下降（或保持不变）
• 在变更日志中记录此次移除

移除依赖项后，有时仍会留下配置文件、CI 钩子或导入语句。请全面搜索。

---

失败模式

没有更新节奏。 依赖会逐渐过时。等到终于升级时，过程会很痛苦。设定固定节奏。

在 CI 中禁用审计。 “噪声太多。” 调整审计配置，不要禁用它。明确将已知误报加入白名单。

所有内容都固定到精确版本。 这会阻止自动应用补丁，也会错过安全修复。使用范围较窄的版本范围，并配合锁文件。

未固定的浮动版本。 在生产环境中使用 latest。构建无法复现。必须使用锁文件。

添加依赖时不进行审核。 “我只是需要一个小工具。” 现在却有 50 个未使用的依赖。新增依赖必须经过审核。

忽略传递依赖。 一个直接依赖会引入 50 个间接依赖。每个依赖都会扩大供应链攻击面。审计整个依赖树，而不只是顶层依赖。

通过升级主版本来打补丁。 “为了修复一个错误而更新”，但更新的是主版本。结果还引入了无关的破坏性更改。谨慎选择修复所用的版本。

供应商捆绑的库。 有些依赖会捆绑其他依赖的副本，因此审计时看不到它们。应定期检查。

认为构建时依赖没有风险。 构建工具可以访问你的代码和凭据。供应链攻击会将它们作为目标。应采取适当的防护措施。

分叉后没有重新同步计划。 为了修复某个问题而分叉依赖，之后就由你负责维护。制定重新同步或合并上游更改的计划，或者承诺维护该分叉。

没有许可证审计。 项目在商业产品中使用了 GPL 依赖。这会造成合规问题。新增依赖时以及每个季度都要审计许可证。

更新 PR 堆积。 Dependabot PR 数月未合并。要么调整设置以减少 PR 数量，要么安排时间合并它们。

---

输出格式

依赖策略文档包括：

• 清单： 按类别列出当前依赖
• 审计状态： 未解决的安全公告、严重程度及处理计划
• 策略： 更新节奏、SLA、版本固定、审批
• 工具： 自动化内容（Renovate、Dependabot、CI 中的审计）
• 许可证审计： 任何需要关注的问题
• 季度审查计划： 何时重新审查

---

参考文件

• references/upgrade-checklist.md：执行关键依赖主版本升级的分步检查清单，涵盖从阅读变更日志到分阶段发布的全过程。