# 依赖管理——生产模式 **现代最佳实践（2026 年 1 月）**：Lockfile-first 工作流程、自动安全扫描（Dependabot、Snyk、Socket.dev）、语义版本控制、最小依赖原则、monorepo 工作区（pnpm、Nx、Turborepo）、供应链安全（SBOM、AI BOM、Sigstore）、可重复构建和 AI 生成的代码验证。 ** ** ## 何时使用此技能当用户请求时，代理应调用此技能： * 向项目添加新的依赖项 * 安全更新现有依赖项 * 解决依赖冲突或版本不匹配的问题 * 审计依赖关系是否存在安全漏洞 * 了解锁文件管理和可重现的构建 * 设置 monorepo 工作区（pnpm、npm、yarn） * 管理传递依赖和覆盖 * 在相似的包之间进行选择（包大小、维护、安全性） * 依赖版本约束和语义版本控制 * 依赖安全最佳实践和供应链安全 * 解决“依赖地狱”场景 * 包管理器配置和优化 * 跨环境创建可重复的构建 ** ** ## 快速参考任务|工具/命令 |关键行动|何时使用 ---|---|---|--- **从锁定文件安装** | `npm ci`、`poetry install`、`cargo build` |干净安装，可重现 | CI/CD、生产部署 **添加依赖** | `npm install `, `poetry add ` |自动更新锁定文件 |新功能需要库 **更新依赖关系** | `npm 更新`、`诗歌更新`、`货物更新` |版本限制内的更新 |每月/每季度维护 **检查漏洞** | `npm 审计`、`pip-audit`、`cargo 审计` |扫描已知 CVE |发布前，每周 **查看依赖关系树** | `npm ls`、`pnpm 为什么`、`pipdeptree` |显示传递依赖 |调试冲突 **覆盖传递 dep** | `覆盖` (npm)、`pnpm.overrides` |强制特定版本|安全补丁、冲突解决 **Monorepo 设置** | `pnpm 工作区`、`npm 工作区` |共享依赖、交叉链接 |多包项目 **检查过时** | `npm 过时了`、`诗歌秀--过时了` |列出可用更新 |规划更新冲刺 ** ** ## 决策树：依赖管理用户需求：【依赖任务】 ├─ 添加新的依赖项？ │ ├─ 检查：我真的需要这个吗？（可以在 <100 LOC 内实现吗？） │ ├─ 检查：保养得好吗？（最后一次提交 <6 个月，>10k 下载/周） │ ├─ 检查：捆绑包大小的影响？（对 JS 使用 Bundlephobia） │ ├─ 检查：安全风险？（`npm 审计`，Snyk） │ └─ 如果所有检查都通过 → 添加`npm install ` → 提交锁文件 │ ├─ 更新依赖？ │ ├─ 安全漏洞？ → `npm 审核修复` → 测试 → 立即部署 │ ├─ 例行更新？ │ ├─ 补丁版本 → `npm update` → 安全，经常做 │ ├─ 次要/主要 → 检查 CHANGELOG → 分期测试 → 逐步更新 │ └─ 一次性全部 → [FAIL] RISKY → 改为分批更新 │ ├─ 依赖冲突？ │ ├─ 传递依赖问题？ │ ├─ 查看树：`npm ls ` │ ├─ 谨慎使用覆盖：package.json 中的 `overrides` │ └─ 记录为什么需要覆盖 │ └─ 对等依赖不匹配？ │ └─ 检查版本兼容性 → 更新父级或子级 │ ├─ Monorepo 项目？ │ ├─ 使用pnpm工作空间（推荐默认） │ ├─ 共享 deps → 根 package.json │ ├─ 包特定 → 包目录 │ └─ 使用Nx或Turborepo进行任务缓存 │ └─ 选择包管理器？ ├─ 新的 JS 项目 → **pnpm** （推荐默认）或 **Bun** （通常更快；验证生态系统成熟度） ├─ Enterprise monorepo → **pnpm** （成熟的工作区支持） ├─ 以速度为中心的实验→ **Bun**（验证生态系统成熟度） ├─ 现有的 npm 项目 → 迁移到 pnpm 或留下（检查团队偏好） ├─ Python → **uv**（快速）、Poetry（成熟）、pip+venv（简单） └─ 数据科学 → **conda** 或 **uv** （更快的环境设置） ** ** ## 导航：核心模式 ### 锁文件管理 **[`references/lockfile-management.md`]()** 锁定文件通过记录所有依赖项（直接+传递）的准确版本来确保可重现的构建。对于防止“在我的机器上运行”问题至关重要。 * 黄金规则（始终提交，绝不手动编辑，更改时重新生成） * 按生态系统的命令（npm ci、poetry install、cargo build） * 解决锁定文件冲突问题 * CI/CD 集成模式 ### 语义版本控制 (SemVer) **[`references/semver-guide.md`]()** 了解版本约束（`^`、`~`、精确）以及如何安全地指定依赖范围。 * SemVer 格式 (MAJOR.MINOR.PATCH) * 版本约束语法（脱字号、波形符、精确） * 按项目类型推荐的策略 * 跨生态系统版本管理 ### 依赖安全审计 **[`references/security-scanning.md`]()** 自动安全扫描、漏洞管理和供应链安全最佳实践。 * 自动化工具（Dependabot、Snyk、GitHub 高级安全性） * 运行审计（npm 审计、pip 审计、cargo 审计） * CI集成和警报配置 * 事件响应工作流程 ### 依赖选择 **[`references/dependency-selection-guide.md`]()** 决定是否添加新的依赖项并在类似的包之间进行选择。 * 最小依赖原则（最好的依赖是你不添加的） * 评估清单（维护、捆绑包大小、安全性、替代方案） * 在相似的软件包之间进行选择（比较矩阵） * 何时拒绝依赖 ### 更新策略 **[`references/update-strategies.md`]()** 安全地保持依赖项最新，同时最大限度地减少重大更改和安全风险。 * 更新策略（持续、计划、仅安全） * 安全更新工作流程（检查过时、风险分类、测试、部署） * 自动更新工具（Dependabot、Renovate、npm-check-updates） * 处理重大变更和回滚计划 ### 单一仓库管理 **[`references/monorepo-patterns.md`]()** 在具有共享依赖关系的单个存储库中管理多个相关包。 * 工作区工具（pnpm、npm、yarn 工作区） * Monorepo 结构和组织 * 构建优化（Nx、Turborepo） * 版本控制和发布策略 ### 传递依赖 **[`references/transitive-dependency.md`]()** 处理依赖项的依赖项（间接依赖项）。 * 查看依赖树（npm ls、pnpm Why、pipdeptree） * 解决传递性冲突（覆盖、解析、约束） * 安全风险和版本冲突 * 最佳实践（谨慎使用、记录、测试） ### 生态系统特定指南 **[`references/ecosystem-guides.md`]()** 特定于语言和包管理器的最佳实践。 * Node.js（npm、yarn、pnpm 比较和最佳实践） * Python（pip、poetry、conda） * Rust（货物）、Go（go mod）、Java（maven、gradle） * PHP（作曲家）、.NET（nuget） ### 反模式 **[`references/anti-patterns.md`]()** 管理依赖项时要避免的常见错误。 * 关键反模式（不提交锁定文件、通配符、忽略审核） * 危险的反模式（从不更新、已弃用的软件包） * 中等反模式（过度使用覆盖、忽略对等部门） ### 容器依赖模式 **[`references/container-dependency-patterns.md`]()** 管理容器化环境（Docker、OCI）中的依赖关系。 * 多阶段构建、图层缓存、基础镜像选择 * 运行时与构建依赖项、图像扫描、可复制图像 ### 版本冲突解决 **[`references/version-conflict-resolution.md`]()** 解决依赖版本冲突的系统方法。 * 钻石依赖问题、生态系统解决算法 * 覆盖策略、兼容性矩阵、迁移路径 ### 许可证合规性 **[`references/license-compliance.md`]()** 开源许可证管理和合规自动化。 * 许可证兼容性矩阵、copyleft 与宽容、SPDX 标识符 * 自动扫描（FOSSA、许可证检查器）、CI 中的策略执行 ** ** ## 导航：模板 ### Node.js **[`assets/nodejs/`]()** * [`package-json-template.json`]() \- 具有最佳实践的生产就绪 package.json * `npmrc-template.txt` \- npm 的团队配置 * [`pnpm-workspace-template.yaml`]() \- Monorepo 工作区设置 ###Python **[`assets/python/`]()** * [`pyproject-toml-template.toml`]() \- 具有最佳实践的 Poet 配置 ### 自动化 **[`assets/automation/`]()** * [`dependabot-config.yml`]() \- GitHub Dependabot 配置 * [`renovate-config.json`]() \- 更新机器人配置 * [`audit-checklist.md`]() \- 安全审核工作流程 * **[`template-supply-chain-security.md`]()** \- **新** SBOM、出处、漏洞管理 * [`template-dependency-upgrade-playbook.md`]() \- 升级批处理、推出、回滚 * [`template-sbom-vuln-triage-checklist.md`]() \- SBOM 映射 + 漏洞分类 ** ** ## 供应链安全 **[assets/automation/template-supply-chain-security.md]()** — 生产级依赖安全性。相关模板： * [assets/automation/template-dependency-upgrade-playbook.md]() * [assets/automation/template-sbom-vuln-triage-checklist.md]() ### 关键部分 * **SBOM 生成** — CycloneDX、SPDX 格式； CI/CD 集成 * **AI BOM（新兴）** — AI 原生系统的扩展 SBOM（模型、数据集、训练工件） * **出处和证明** — SLSA 级别、Sigstore 签名、npm 出处 * **漏洞管理** — 分类工作流程、严重性 SLA、扫描工具 * **升级 Playbooks** — 批处理策略、回滚程序 * **固定和可重复性** — 锁定文件、哈希固定、版本约束 * **《欧盟网络弹性法案》** — SBOM 要求于 2027 年 12 月生效 ### 做/避免 #### 好：做 * 为每个版本生成SBOM * 签名发布工件（Sigstore/cosign） * 在 CI/CD 中运行漏洞扫描 * 24小时内修复严重漏洞 * 使用锁文件进行可重现的构建 * 验证npm包的来源 * 按风险级别批量非安全更新 #### 坏：避免 * 不使用 SBOM 进行发布 * 在生产中使用未签名的包 * 忽略漏洞扫描器输出 * 一次性更新所有依赖项 * 使用通配符版本范围（`*`、`>=`） * 提交而不更新锁文件 * 绕过安全门“就这一次” ### 反模式反模式 |问题 |修复 ---|---|--- **无 SBOM** |无法应对供应链攻击|在 CI/CD 中生成 SBOM **未签名的工件** |篡改无法检测 |使用 Sigstore 签名 **浮动版本** |构建不可重现|使用锁定文件+精确版本 **一次性更新** |难以平分回归|按风险等级分批 **在 CI 中安装 npm** |不确定性 |使用“npm ci” **无审核门** |漏洞交付产品 |审计门部署 ** ** ## 人工智能产生的依赖风险 > **警告**：AI 编码代理可能会大规模引入易受攻击或不存在的软件包（Endor Labs，2025）。 ### 问题人工智能工具加速编码但引入供应链风险： * **幻觉包** — AI 建议不存在的包（误植向量） * **易受攻击的依赖项** — AI 建议过时或受 CVE 影响的版本 * **不必要的依赖** - AI 过度依赖包来完成简单任务 ### 最佳实践做|不要 ---|--- 将人工智能生成的代码视为不受信任的第三方输入 |盲目接受AI依赖建议对 AI 生成的代码执行相同的 SAST/SCA 扫描 |跳过“人工智能编写”代码的安全审查验证所有 AI 建议的软件包是否确实存在 |信任 AI 了解当前的软件包版本将安全工具集成到 AI 工作流程 (MCP) |允许AI无需审核即可添加依赖项 Vet MCP 服务器作为供应链的一部分 |使用未经审查的人工智能集成 ### 验证清单在接受 AI 建议的依赖项之前： * 包存在于注册表中（npm、PyPI、crates.io） * 包名称拼写正确（无拼写错误） * 版本为最新版本并已维护 * `npmaudit`/`pip-audit` 显示没有漏洞 * 每周下载量>1000（已建包） * 最后一次提交 <6 个月（积极维护） ** ** ## 可选：人工智能/自动化 > **注意**：人工智能协助分类，但安全决策需要人类判断。 * **自动 PR 分类** — 按风险对依赖项更新进行分类 * **变更日志摘要** - 总结更新中的重大变更 * **漏洞关联** — 将 CVE 链接到受影响的包 ### 有界声明 * 人工智能无法确定业务风险接受程度 * 自动修复需要安全团队审核 * 漏洞严重程度上下文需要人工验证 ** ** ## 快速决策矩阵场景|推荐 ---|--- 添加新的依赖项 |检查 Bundlephobia、npm 审核、每周下载、上次提交更新依赖项 |使用`npm outdated`，批量更新，在staging中测试发现安全漏洞 |使用“npmauditfix”，查看变更日志，测试，立即部署 Monorepo 设置 |使用 **pnpm 工作区** 或 Nx/Turborepo 进行构建缓存传递性冲突 |谨慎使用“覆盖”，记录原因，彻底测试选择 JS 包管理器 | **pnpm**（最快，磁盘效率最高），**Bun**（快 7 倍），npm（最兼容） Python环境| **uv**（快 10-100 倍）、Poetry（成熟）、pip+venv（简单）、conda（数据科学） ** ** ## 核心原则 ### 1\.始终提交锁定文件锁定文件确保跨环境的可重复构建。切勿将它们添加到“.gitignore”中。 **例外**：不要为 Rust 库提交 `Cargo.lock`（仅适用于应用程序）。 ### 2\.使用语义版本控制对于大多数依赖项使用脱字符号 (`^`)，对于关键任务使用精确版本，避免使用通配符 (`*`)。 { “依赖项”：{ "express": "^4.18.0", // 允许补丁和次要版本 "ritic-lib": "1.2.3" // 精确用于关键 } } ### 3\.定期审计依赖关系每周进行安全审核，立即修复关键漏洞。新项目管理审计 npm 审计修复 ### 4\.最小化依赖性最好的依赖是您不添加的依赖。问：我可以在 <100 LOC 内实现这个吗？ ### 5\.定期更新每月或每季度更新。不要让技术债务累积。 npm 过时了 npm 更新 ### 6\.谨慎使用覆盖仅覆盖安全补丁或冲突的传递依赖项。记录原因。 { “覆盖”：{ "axios": "1.6.0" // CVE-2023-xxxxx 修复 } } ** ** ## 相关技能对于补充工作流程和更深入的研究： * [`dev-api-design`]() \- API 版本控制策略、依赖注入模式 * [`git-workflow`]() \- 用于管理锁定文件冲突、分支策略的 Git 工作流程 * [`qa-testing-strategy`]() \- 依赖项更新、集成测试的测试策略 * [`software-security-appsec`]() \- OWASP Top 10、加密标准、身份验证模式 * [`ops-devops-platform`]() \- CI/CD 管道、Docker 容器化、DevSecOps、部署自动化 * [`docs-codebase`]() \- 记录依赖项选择、ADR、变更日志 ** ** ## 外部资源有关精选资源，请参阅 [`data/sources.json`]()： * **包管理器**：npm、pnpm、Yarn、pip、Poetry、Cargo、Go 模块、Maven、Composer * **语义版本控制**：SemVer 规范、版本计算器、约束引用 * **安全工具**：Snyk、Dependabot、GitHub Advanced Security、OWASP Dependency-Check、pip-audit、cargo-audit、Socket.dev、Renovate * **锁文件管理** ：package-lock.json、poetry.lock、Cargo.lock、pnpm-lock.yaml 的官方文档 * **Monorepo 工具** ：pnpm 工作区、npm 工作区、Yarn 工作区、Nx、Turborepo、Lerna、Bazel * **分析工具**：Bundlephobia、npm-check-updates、depcheck、pipdeptree、cargo tree * **供应链安全**：SLSA 框架、SBOM (CISA)、Sigstore、npm 出处、OpenSSF 记分卡 * **最佳实践**：npm/Poetry/Cargo 指南、ACM 队列文章、依赖地狱参考 * **版本管理**：nvm、pyenv、rustup、asdf * **学习资源** ：npm 指南、Python 打包用户指南、Rust Book、Monorepo.tools ** ** ## 使用说明 **对于法典/克劳德代码：** * 当用户需要依赖管理指导时使用此技能 * 根据任务引用特定资源（锁定文件、安全性、更新） * 提供特定于生态系统的指导（Node.js、Python、Rust） * 始终推荐安全审核和可重现的构建 * 鼓励最小的依赖和定期更新 * 链接到常见配置的模板 **最佳实践：** * 始终提交锁文件（库的 Cargo.lock 除外） * 使用语义版本控制（插入符表示大多数部门，精确表示关键） * 每周审计依赖项（`npmaudit`、`pip-audit`、`cargoaudit`） * 每月或每季度更新依赖项（不是一次全部更新） * 根据项目需求选择包管理器（pnpm 用于速度，Poetry 用于 Python 应用程序） * 在 ADR（架构决策记录）中记录依赖项选择 ** ** > **成功标准：** 依赖性最小、维护良好、安全、跨环境可重现，并定期审核漏洞。 ** ** ## 趋势认知协议 **重要**：当用户询问有关包管理器、依赖工具或供应链安全的推荐问题时，您必须在回答之前使用 WebSearch 检查当前趋势。 ### 触发条件 *“[生态系统]最好的包管理器是什么？” *“我应该使用什么来[依赖管理/安全]？” *“依赖管理的最新进展是什么？” *“[npm/pnpm/Poetry] 目前的最佳实践？” *“[工具/方法]在 2026 年仍然适用吗？” *“[pnpm] vs [npm] vs [yarn]？” *“最好的依赖安全扫描器？” ### 必填搜索 1. 搜索：`“2026 年依赖管理最佳实践”` 2. 搜索：`“[特定工具] vs 2026 替代品”` 3.搜索：`“2026年1月供应链安全趋势”` 4. 搜索：`“[包管理器] features 2026”` ### 报告内容搜索后，提供： * **当前情况**：现在流行哪些依赖工具 * **新兴趋势**：新的包管理器、安全工具或模式受到关注 * **已弃用/下降**：工具/方法失去相关性或支持 * **推荐** ：基于新鲜数据，而不仅仅是静态知识 ### 示例主题（使用新搜索验证） * 包管理器（Python 的 pnpm、npm、yarn、Poetry、uv） * 安全扫描（Snyk、Dependabot、Socket.dev） * 供应链安全（SBOM、Sigstore、SLSA） * Monorepo 工具（Nx、Turborepo、Bazel） * 锁定文件和可重复性模式 * 自动依赖更新（Renovate、Dependabot） ## 操作预检：依赖关系和工具链运行状况（针对 LLM 代理）在构建/测试/编辑循环之前运行此命令，以防止可避免的混乱，例如“下一个：找不到命令”。 # 1) 运行时 + 包管理器的完整性节点-v npm -v # 2) 锁定文件和安装模式 ls -1 package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null 测试-d节点模块||国家管理委员会 # 3) 验证框架二进制文件解析 npx next --version 2>/dev/null || echo“下一个失踪” npx eslint --版本 2>/dev/null || echo "eslint 缺失" # 4) 早期的表面依赖图问题 npm ls --深度=0 ### 补救规则 * 如果二进制文件丢失：从锁定文件安装，不要临时安装随机版本。 * 如果检测到锁定文件漂移：使用项目标准工具（`npm ci`、`pnpm install --frozen-lockfile` 等）重新安装。 * 如果出现对等依赖冲突，请在继续广泛编辑之前修复根本原因。 * 在会话启动时缓存这些检查，以便长时间代理运行。

开发依赖管理

包含技能