dependency-management

依赖管理

第三方依赖既是现代软件中最强大的部分，也是最危险的部分。一次依赖管理不当就造成了 log4shell 事件。Left-pad 在 11 分钟内导致数千个构建失败。通过依赖混淆发动的供应链攻击波及了大型企业。本技能涵盖依赖的完整生命周期：以面向生产环境的严谨标准进行选择、锁定版本、审计、更新和移除。

何时使用

适用于：

• 决定是否添加新的依赖
• 制定版本锁定策略（精确版本、范围或仅使用锁文件）
• 设置自动更新工作流（Renovate、Dependabot）
• 使用 npm audit、pip audit、Snyk、Socket.dev 进行安全审计
• 扫描许可证合规性（MIT/Apache/GPL 兼容性）
• 生成软件物料清单（SBOM）
• 解决 peer 依赖冲突和 npm overrides
• 响应安全公告和 CVE
• 检测仿冒拼写攻击和依赖混淆攻击

不适用于：

• 内部 monorepo 包管理（请使用 monorepo-management）
• 将自己的包发布到 npm、PyPI、crates.io
• 超出依赖管理范围的包管理器配置（工作区配置等）
• 供应商化和隔离网络环境（请注意这些场景确实存在，但不在本指南范围内）

---

核心决策：我应该添加这个依赖吗？

flowchart TD
    Start[Want to add a dependency?] --> Size{How much code does it replace?}
    Size -->|< 20 lines| Write[Write it yourself]
    Size -->|20-200 lines| Q2{Trivial to implement correctly?}
    Size -->|> 200 lines| Q3{Check the package}

    Q2 -->|Yes, pure logic| Write
    Q2 -->|No, edge cases / locale / timezone| Q3

    Q3 --> Audit{Run audit checks}
    Audit --> Downloads{Weekly downloads?}
    Downloads -->|< 10k| HighRisk[High risk: low adoption]
    Downloads -->|10k-100k| MedRisk[Medium: check actively]
    Downloads -->|> 100k| Maintained{Actively maintained?}

    Maintained -->|Last commit > 2 years| Fork[Consider fork or alternative]
    Maintained -->|Recent commits| License{License compatible?}

    License -->|GPL in proprietary| Reject[REJECT: license issue]
    License -->|MIT / Apache 2.0| Security{npm audit / Socket.dev scan?}

    Security -->|CVEs unfixed| Reject
    Security -->|Clean| Transitive{Transitive dep count?}

    Transitive -->|> 50 new deps| Reconsider[Reconsider: high blast radius]
    Transitive -->|< 50 new deps| Accept[Add with pinned version]

    HighRisk --> Fork
    MedRisk --> Maintained

---

版本锁定策略

Semver 语义回顾

^1.2.3  = >= 1.2.3, < 2.0.0   (minor + patch updates allowed)
~1.2.3  = >= 1.2.3, < 1.3.0   (patch updates only)
1.2.3   = exactly 1.2.3        (locked)
*       = any version           (never use)

何时使用哪种策略

策略	用途	原因
精确锁定（1.2.3）	生产应用	构建可复现；锁文件提供灵活性
波浪号（~1.2.3）	要发布的库	补丁版本安全；次版本可能破坏使用方
插入符号（^1.2.3）	仅用于开发工具	对格式化工具、代码检查工具而言，可接受版本变动
以锁文件为准	所有生产环境	npm ci、pip install --frozen、cargo build
绝不使用 *	任何场景	后果严重：构建时会安装最新版本，无论是什么版本

反模式：在生产应用依赖中使用插入符号

新手：“我使用 ^，这样就能自动获取所有错误修复版本，更安全。” 专家：插入符号范围意味着任何符合 semver 规则、但可能带有破坏性变更的版本，都会在你不知情的情况下安装。Semver 只是期望，并非强制执行——软件包经常在次版本中发布破坏性变更。锁文件可以防止开发者机器上的这种情况，但运行 npm install 而不是 npm ci 的 CI 环境会悄悄升级。精确锁定直接依赖，并通过 Renovate 或 Dependabot PR 有计划地审核更新。 检测：检查生产应用的 package.json 中，运行时依赖是否带有 ^ 前缀。在全新克隆的项目上运行 npm ci，并将安装后的依赖树与上次部署时的依赖树进行比较。

---

更新工作流决策

flowchart TD
    Update[How to handle updates?] --> Auto{Use automation?}
    Auto -->|Yes| Tool{Which tool?}
    Auto -->|No, manual| Manual[Monthly audit: npm outdated / pip list --outdated]

    Tool -->|GitHub repo| Dependabot[GitHub Dependabot]
    Tool -->|Any platform| Renovate[Renovate Bot — more powerful]

    Dependabot --> DConfig[Configure .github/dependabot.yml]
    Renovate --> RConfig[Configure renovate.json]

    DConfig --> DGroup{Group updates?}
    RConfig --> RGroup{Group updates?}

    DGroup -->|Yes| DGrouped[Group patch updates together]
    DGroup -->|No| DPR[One PR per dependency]
    RGroup -->|Yes| RGrouped[Group by type: devDeps patch / prod minor]
    RGroup -->|No| RPR[One PR per dependency]

    RGrouped --> AutoMerge{Automerge safe?}
    DGrouped --> AutoMerge

    AutoMerge -->|Dev deps + patch only| EnableAM[Enable automerge with test gate]
    AutoMerge -->|Prod deps, major versions| RequireReview[Require human review]

---

安全审计

审计工具链

按以下顺序运行，从速度最快、免费的工具开始，逐步深入：

# 1. npm audit (built-in, free, fast — checks known CVEs)
npm audit
npm audit --audit-level=high    # Only high+ severity
npm audit fix                   # Auto-fix where possible
npm audit fix --force           # ⚠️ May break API — review first

# 2. pip audit (Python equivalent)
pip install pip-audit
pip-audit
pip-audit --fix                 # Write fixed requirements.txt

# 3. Socket.dev (supply chain analysis beyond CVEs)
npx socket check                # Checks for malicious behavior, typosquatting

# 4. Snyk (deeper analysis, CI integration)
npx snyk test
npx snyk monitor                # Continuous monitoring

# 5. SBOM generation (for compliance)
npx @cyclonedx/cyclonedx-npm --output-format json > sbom.json
# Python: pip install cyclonedx-bom && cyclonedx-py -p

反模式：忽略安全公告

新手：“审计发现了漏洞，但它们存在于开发依赖或未使用的代码路径中，不构成风险。” 专家：开发依赖有两种方式会影响生产环境：（1）处理生产代码的构建工具可能遭到入侵；（2）安全公告可能将软件包标为“仅限开发环境”，但该软件包实际上已包含在你的生产包中。使用 npm ls <package> 检查依赖链。对于确实仅用于开发环境的软件包（mocha、jest、eslint），可以推迟处理中等级别的安全公告。严重或高危漏洞——即使存在于开发依赖中——也应在 SLA 规定的时限内解决。“不构成风险”是一项评估，不是忽略问题的理由；请记录评估结论。 检测：运行 npm audit --production，将审计范围限定为仅用于生产环境的依赖。运行 npm ls <vulnerable-pkg>，查看所有依赖该软件包的程序。

---

供应链安全

拼写仿冒检测

常见攻击模式：

• lodash → 1odash（用数字 1 替代字母 l）
• express → expres（缺少字符）
• react → React（大小写不同——区分大小写的注册表）
• @org/package → org-package（作用域混淆）

# Socket.dev catches most of these
npx socket check

# Manual: verify before install
npm view <package-name>         # Check metadata: author, description, repo URL
npm view <package-name> repository  # Verify GitHub repo matches official source

依赖混淆攻击

攻击者发布一个与您的私有 @org/package 同名的公共包。由于公共包的版本号更高，包管理器会获取公共包。

预防：

# npm: Use .npmrc scoped registry config
@your-org:registry=https://your-private-registry.example.com

# Or set resolutions/overrides to lock the source
# package.json:
{
  "overrides": {
    "@your-org/internal-package": "npm:@your-org/internal-package@^1.0.0"
  }
}

锁文件完整性

# Never commit node_modules — commit only the lockfile
# Verify lockfile integrity after pulls
npm ci                          # Fails if lockfile doesn't match package.json
                                # NEVER use npm install in CI

# Python: use pip-compile for deterministic locks
pip install pip-tools
pip-compile requirements.in     # Generates pinned requirements.txt
pip-sync requirements.txt       # Install exactly this

---

许可证合规性

兼容性矩阵

您的项目	MIT 依赖项	Apache 2.0 依赖项	LGPL 依赖项	GPL 依赖项
专有	可接受	可接受（需注明出处）	可接受（动态链接）	拒绝
MIT/Apache	可接受	可接受	可接受	情况复杂
GPL	可接受	可接受	可接受	可接受

# Scan all licenses in your dependency tree
npx license-checker --production --onlyAllow "MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC;0BSD"
npx license-checker --production --failOn "GPL;AGPL"

# Python
pip install pip-licenses
pip-licenses --format=markdown --order=license

反模式：为简单功能引入过多依赖项

新手：npm install is-odd（实际存在的包，每周下载量为 54M）。安装一个只有 1 行代码的包：n % 2 !== 0。 专家：left-pad 事件（2016 年）证明，简单的工具包会带来运营风险。每个生产依赖项都可能成为 CVE 攻击途径、供应链攻击面、语义化版本冲突源和认知负担。在添加包之前，将 README 粘贴到 ChatGPT 中并询问“核心功能是否少于 20 行？”对于日期处理、字符串工具和数学运算，请自行编写函数。对于本地化、密码学和协议解析，请使用经过实战检验的库。 检测：运行 npx cost-of-modules，或在 npm 页面查看源代码大小。对于非简单领域，大小低于 10KB 的包几乎总是可以替换。 时间线：left-pad 事件之后（2016 年），生态系统对此更加重视，但这种模式仍然存在。2024 年的 polyfill.io CDN 遭入侵事件表明，CDN 依赖项也存在同样的问题。

---

npm Overrides 和 Resolutions

当直接依赖项尚未更新时，可用它们修复存在漏洞的传递依赖项：

// package.json — npm overrides (npm 8.3+)
{
  "overrides": {
    "semver": ">=7.5.2",           // Force minimum version across all deps
    "lodash": "4.17.21",           // Force exact version
    "vulnerable-pkg": {
      "sub-dependency": "^2.0.0"   // Scoped: only for this parent
    }
  }
}

// package.json — yarn/pnpm resolutions
{
  "resolutions": {
    "semver": ">=7.5.2"
  }
}

注意：Overrides 可能会导致确实需要旧 API 的包无法正常工作。添加 overrides 后，务必运行测试套件。

---

对等依赖项

# Check what peer deps a package needs
npm info <package> peerDependencies

# npm 7+ auto-installs peer deps (may surprise you with version conflicts)
# Opt out: npm install --legacy-peer-deps (last resort)

# Check for peer dep conflicts
npm install 2>&1 | grep "peer dep"
npm ls 2>&1 | grep "WARN" | grep "peer"

规则：如果看到对等依赖项警告，不要将其忽略。这些警告表示版本不匹配，可能导致难以察觉的运行时故障。可通过将通用对等依赖项固定到兼容版本来解决。

---

参考资料

• references/update-strategies.md — 查阅 Renovate 与 Dependabot 配置详情、分组策略、自动合并政策，以及安全测试更新 PR 的方法
• references/security-auditing.md — 查阅 npm audit / Snyk / Socket.dev 的深入介绍、SBOM 生成、许可证扫描工具和 CI 集成模式