dependency-upgrade

依赖升级

相关技能

• sap-hana-cli：用于依赖感知型数据库工具工作流和升级指导
• sap-cap-capire：用于 CAP 依赖安全的运行时和服务配置指导
• sap-fiori-tools：用于工具涉及前端软件包时，制定安全的 UI5/Fiori 依赖策略

通过供应链安全、兼容性分析、分阶段发布和全面测试，管理所有主要软件包管理器的依赖升级。

何时使用此技能

• 升级主要框架或库的版本
• 配置供应链攻击防护（冷却期、脚本阻止、锁文件加固）
• 设置安全的软件包管理器配置
• 解决依赖冲突或 peer 依赖问题
• 规划并通过测试验证渐进式升级路径
• 使用 Renovate、Dependabot 或 Snyk 自动更新依赖
• 审计依赖中的漏洞
• 设置 CI/CD 依赖安全工作流

两种操作模式

交互式——通过设置问题生成量身定制的配置。适用于全新设置。

默认——立即应用推荐默认值：7 天冷却期、阻止所有脚本、frozen-lockfile、lockfile-lint，以及启用冷却期的 Dependabot。可选择自定义。

交互式设置流程

用户需要量身定制的配置时，请逐步确认以下选项。使用默认模式时，请完全跳过本节。

第 1 层：必需选项

生成任何配置前，始终先询问以下 3 个问题：

1. 软件包管理器

“此项目使用哪个软件包管理器？”

答案	生成的文件
npm	.npmrc
Bun	bunfig.toml
pnpm	pnpm-workspace.yaml
Yarn	.yarnrc.yml
Deno	deno.json 配置

2. 冷却期

“新发布的软件包在安装前应经过多少天的冷却期？这可以防止供应链攻击：恶意软件包可能在几天内被发现并撤下。”

选项	天数	使用场景
激进	3	可发现大多数拼写抢注
推荐	7	适合大多数项目的良好平衡
保守	14	关键系统/生产系统
偏执	21	与 Snyk 的内置默认值一致
自定义	N	由用户指定

3. 安装后脚本策略

“应如何处理生命周期脚本（postinstall、preinstall）？它们是供应链攻击的头号攻击途径。”

选项	行为
全部阻止（推荐）	--ignore-scripts + allow-git=none
允许列表	默认阻止，仅允许特定的可信软件包
仅审查	发出警告，但不阻止

第 2 层：安全工具（批量提供）

“您想配置以下哪些安全功能？可多选。”

4. CI/CD 自动化工具

答案	生成内容
Dependabot	带有冷却期的 .github/dependabot.yml
Renovate	带有 minimumReleaseAge 的 renovate.json
Snyk	无需配置（内置 21 天冷却期）
无	跳过

5. 自动合并策略

选项	行为
无	所有更新都需要手动审核
仅 Minor+Patch	自动合并安全更新，Major 版本需审核
全部合并，但需批准	团队批准后自动合并

6. 更新计划

选项	配置值
每日	"daily"
每周（默认）	"weekly"
每两周	"biweekly"
每月	"monthly"

7. 安装时安全工具

“哪些安全工具应保护依赖项安装？”

选项	免费？	功能
socket npm wrapper	是（测试版）	包装 npm/npx，在安装前阻止恶意软件包。运行 socket wrapper on 即可启用系统级保护。
npq	是	安装前审查工具（检查 CVE、拼写仿冒、包的年龄和来源证明）
Socket Firewall (sfw)	否	实时深度分析，阻止恶意软件包
socket npm + npq	是	组合使用这两款免费工具
无	—	跳过

加载 references/socket-cli-guide.md，查看完整的 Socket CLI 设置说明，包括身份验证以及免费功能与需身份验证功能的区别。

8. 锁文件验证

选项	行为
是（推荐）	添加 lockfile-lint + CI 脚本
否	跳过

第 3 层：高级选项（仅在用户选择时提供）

“您想配置任何高级选项吗？”

9. 开发容器 — 生成强化后的 .devcontainer/devcontainer.json（是/否）

10. 密钥管理器 — 1Password CLI / Infisical / 无

11. pnpm 信任策略 — 启用 trustPolicy: no-downgrade（仅限 pnpm 10.21+，是/否）

12. 冷却期例外 — 可绕过冷却期的软件包名称（例如，@types/react、typescript、esbuild）

安全优先的升级原则

1. 安装前设置冷却期 — 等待 7 天，让社区审核新版本的软件包
2. 阻止安装后脚本 — 防止在 npm install 期间执行任意代码
3. 在 CI 中冻结锁文件 — 使用确定性安装（npm ci、--frozen-lockfile）
4. 验证锁文件完整性 — 使用 lockfile-lint 检测注入
5. 先审查，再信任 — 使用 npq 或 Socket CLI 在安装前检查软件包
6. 逐步升级 — 每次只升级一个 Major 版本，并在每次升级之间进行测试
7. 切勿盲目升级 — 避免在未经审核的情况下运行 npm update 或 npm-check-updates -u
8. 升级前后都进行扫描 — 使用 socket scan 检测 CVE 之外的供应链问题

冷却期：防范供应链攻击

新发布的软件包可能包含恶意代码，这些代码可能在数小时内被发现。配置冷却期，延迟安装。

快速设置

npm（.npmrc）：

min-release-age=7

Bun（bunfig.toml）：

[install]
minimumReleaseAge = 604800  # 7 days in seconds
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

pnpm（pnpm-workspace.yaml）：

minimumReleaseAge: 10080  # 7 days in minutes
minimumReleaseAgeExclude:
  - '@types/react'
  - typescript

Yarn（.yarnrc.yml）：

npmMinimalAgeGate: "7d"
npmPreapprovedPackages:
  - "@types/react"
  - "typescript"

加载 references/cooldown-config-guide.md，查看各包管理器的详细配置、CI 工具集成和排除规则。

使用 templates/<pm>-security.tmpl 获取可直接复制粘贴的配置文件。

禁用安装后脚本

安装后脚本是最常见的供应链攻击途径（Shai-Hulud、Nx、event-stream 事件）。

快速设置

npm：

npm config set ignore-scripts true
npm config set allow-git none

Bun：默认禁用。在 package.json 中允许特定软件包：

{ "trustedDependencies": ["esbuild", "sharp"] }

pnpm (10.0+)：默认禁用。在 pnpm-workspace.yaml 中允许特定软件包：

allowBuilds:
  esbuild: true
strictDepBuilds: true  # Hard error on unreviewed scripts

加载 references/package-manager-security.md，查看各包管理器的完整加固说明，包括 pnpm trustPolicy、blockExoticSubdeps 和 @lavamoat/allow-scripts。

确定性与冻结安装

在 CI 中始终使用冻结安装命令，以确保构建可复现：

包管理器	命令	作用
npm	npm ci	删除 node_modules，安装锁文件中的确切版本
Bun	bun install --frozen-lockfile	如果锁文件不同步则失败
pnpm	pnpm install --frozen-lockfile	如果锁文件不同步则失败
Yarn	yarn install --immutable --immutable-cache	验证锁文件和缓存
Deno	deno install --frozen	冻结安装

将所有锁文件提交到版本控制中：package-lock.json、bun.lock、pnpm-lock.yaml、yarn.lock、deno.lock。

锁文件验证

安装并配置 lockfile-lint，以检测锁文件注入攻击：

npm install --save-dev lockfile-lint

{
  "scripts": {
    "lint:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https",
    "preinstall": "npm run lint:lockfile"
  }
}

注意：lockfile-lint 目前不支持 Bun 的 bun.lock / bun.lockb 格式。

安装前安全审计

npq — 安装前审计工具

npm install -g npq
npq install <package>          # Audit before installing
npq install <package> --dry-run # Audit without installing

# Shell alias for seamless use
alias npm='npq-hero'

# Use with other PMs
NPQ_PKG_MGR=pnpm npq install <package>
NPQ_PKG_MGR=bun npq install <package>

Socket Firewall (sfw) — 实时拦截工具

npm install -g sfw
sfw npm install <package>      # Blocks malicious packages
sfw pnpm add <package>
sfw yarn add <package>

加载 references/supply-chain-security.md，查看 npq 与 sfw 的完整对比，以及各自的验证内容。

Socket CLI 集成

Socket CLI 提供了超越基础漏洞扫描的主动供应链安全防护，涵盖恶意软件检测、拼写仿冒、抗议软件、安装脚本风险和许可证合规性。

主动升级工作流

1. PRE-UPGRADE:   socket scan create --report          → establish baseline
2. EVALUATE:      socket package score npm <pkg>@<ver>  → assess target package safety
3. SAFE INSTALL:  socket npm install <pkg>              → block malicious packages
4. POST-UPGRADE:  socket scan create --report          → verify no new alerts
5. DIFF:          socket scan diff <before> <after>     → see exactly what changed
6. FIX:           socket fix --minimum-release-age 7d   → auto-fix any new CVEs
7. OPTIMIZE:      socket optimize                       → apply security overrides

快速参考

# Install
npm install -g socket

# Authenticate (required for scans, fixes, package scores)
socket login

# Check a package before upgrading
socket package score npm <package>

# Scan your whole project
socket scan create --report

# Auto-fix CVEs (complements Dependabot/Renovate)
socket fix --minimum-release-age 7d

# Gate CI on security policy
socket ci

# Safe npm wrapper (free, no auth needed)
socket wrapper on

加载 references/socket-cli-guide.md，查看完整的命令参考、CI 工作流模板、警报类别，以及免费与已认证功能对照表。

依赖分析

# Audit for vulnerabilities
bun audit       # Bun
npm audit       # npm
yarn audit      # Yarn

# Socket: deep security assessment (CVEs + supply chain + license)
socket package score npm <package>
socket scan create --report

# Check for outdated packages
bun outdated
npm outdated

# Interactive upgrade (safe — review each)
bunx npm-check-updates --interactive

# Analyze dependency tree
npm ls <package-name>
yarn why <package-name>

分阶段升级策略

每次只升级一个依赖，并在每次升级后进行测试：

# 1. Create feature branch
git checkout -b upgrade/<package>-<version>

# 2. (Optional) Baseline scan — capture current state
socket scan create --report

# 3. Evaluate target package before upgrading
socket package score npm <package>@<version>

# 4. Upgrade single package
bun add <package>@<version>

# 5. Test immediately
bun test && bunx tsc --noEmit && bun run build

# 6. (Optional) Post-upgrade scan — verify no new alerts
socket scan create --report

# 7. Commit and continue
git add -A && git commit -m "chore: upgrade <package> to <version>"

加载 references/staged-upgrades.md，了解 codemod 自动化、自定义迁移脚本和 peer 依赖处理。

加载 references/compatibility-matrix.md，查看版本兼容性表（React 18/19、Next.js 13-15、TypeScript、Tailwind 3/4）。

通过冷却期自动更新

配置 CI/CD 工具遵守冷却期：

Dependabot（.github/dependabot.yml）

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 7

Renovate（renovate.json）

{
  "extends": ["config:base"],
  "minimumReleaseAge": "7 days",
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "minimumReleaseAge": "14 days"
    }
  ]
}

Snyk

Snyk 内置了针对升级 PR 的 21 天冷却期。无需配置。

Socket Fix（与 Dependabot/Renovate 配合使用）

Socket Fix 会通过智能升级规划自动修复 CVE。它与其他自动化工具一同运行，专注于 CVE 修复：

# Fix all fixable CVEs with cooldown alignment
socket fix --minimum-release-age 7d

# Conservative: no major version bumps
socket fix --minimum-release-age 7d --no-major-updates

# Target specific CVEs
socket fix --id GHSA-hhq3-ff78-jv3g --minimum-release-age 7d

# Preview without applying
socket fix --no-apply-fixes --minimum-release-age 7d

如需使用 CI 自动驾驶模式（自动创建并自动合并修复 PR），请使用 templates/socket-fix-ci.tmpl。

加载 references/socket-cli-guide.md，查看完整的 socket fix 选项，包括 --autopilot、--range-style 和 --pr-limit。

使用 templates/dependabot-security.tmpl 或 templates/renovate-security.tmpl 获取完整配置文件。

发布安全

适用于软件包维护者：

# Enable 2FA
npm profile enable-2fa auth-and-writes

# Publish with provenance (cryptographic build proof)
npm publish --provenance

# Trusted publishing via OIDC (eliminates long-lived tokens)
# Configure on npmjs.com, then:
# In GitHub Actions: permissions: id-token: write

加载 references/supply-chain-security.md，查看完整的发布安全指南，包括 OIDC 设置和依赖树精简。

开发环境加固

将依赖执行与宿主系统隔离：

• 开发容器 — 限制恶意软件包的影响范围
• 机密管理 — 使用 1Password CLI 或 Infisical，替代明文 .env 文件
• 依赖树精简 — 用原生 JS 替代常用软件包

使用 templates/devcontainer-security.tmpl 获取加固后的开发容器配置。

加载 references/secrets-and-containers.md，了解开发容器设置、机密管理和依赖精简模式。

测试策略

每次升级后都要在各个层级运行测试：

# 1. Static analysis (fastest)
bunx tsc --noEmit && bun run lint

# 2. Unit tests
bun test

# 3. Build check
bun run build

# 4. Integration / E2E (after major upgrades)
bun run test:e2e

加载 references/testing-strategy.md，查看完整的测试金字塔、CI 集成和包分析。

回滚计划

#!/bin/bash
git stash
git checkout -b upgrade/<package>

bun add <package>@latest

if bun test && bun run build; then
  git add package.json bun.lock
  git commit -m "chore: upgrade <package>"
else
  echo "Upgrade failed, rolling back"
  git checkout main
  git branch -D upgrade/<package>
  bun install
fi

升级检查清单

Pre-Upgrade:
- [ ] Review current dependency versions
- [ ] Read changelogs for breaking changes
- [ ] Create feature branch
- [ ] Tag current state (git tag pre-upgrade)
- [ ] Run full test suite (baseline)
- [ ] Verify cooldown period is configured

Security Pre-Checks:
- [ ] Post-install scripts are disabled
- [ ] Lockfile validation is active
- [ ] Install auditing tools configured (if applicable)
- [ ] CI uses frozen-lockfile install
- [ ] Run `socket scan create --report` for baseline (if Socket available)

During Upgrade:
- [ ] Upgrade one dependency at a time
- [ ] Check target package: `socket package score npm <pkg>` (if Socket available)
- [ ] Respect cooldown period (don't force latest)
- [ ] Update peer dependencies
- [ ] Fix TypeScript errors
- [ ] Run test suite after each upgrade
- [ ] Check bundle size impact

Post-Upgrade:
- [ ] Post-upgrade scan: `socket scan diff` to verify no new alerts (if Socket available)
- [ ] Consider `socket fix --minimum-release-age 7d` for any new CVEs
- [ ] Full regression testing
- [ ] Performance testing
- [ ] Update documentation
- [ ] Deploy to staging
- [ ] Monitor for errors
- [ ] Deploy to production

常见陷阱

• 一次性升级所有依赖项（应逐步升级）
• 不经审查就盲目运行 npm update 或 npm-check-updates -u
• 每次单独升级后都不进行测试
• 忽略对等依赖警告
• 忘记更新或提交锁定文件
• 不阅读变更日志中的重大变更说明
• 跳过主版本，而不是逐个版本升级
• 没有回滚计划
• 轻信 npmjs.org 上显示的源代码（可能与实际的 tarball 不同）
• 保持启用安装后脚本（这是最常见的攻击途径）
• 未为新版本的软件包配置冷却期

何时加载参考资料

当用户需要了解 SKILL.md 快速参考之外的详细信息时，加载以下参考文件：

加载此文件	适用场景
references/cooldown-config-guide.md	为特定 PM 配置冷却期、集成 CI 工具或设置排除模式
references/package-manager-security.md	完整的各 PM 加固指南，包括 pnpm 信任策略、blockExoticSubdeps、跨 PM 速查表
references/supply-chain-security.md	了解攻击途径、事件历史、npq 与 sfw 及 Socket CLI 的比较、发布者安全（2FA、来源证明、OIDC）
references/secrets-and-containers.md	设置开发容器，以及使用 1Password/Infisical 管理密钥
references/socket-cli-guide.md	使用 Socket CLI 进行扫描、修复、软件包评分、CI 集成、封装模式和警报类别
references/compatibility-matrix.md	检查 React、Next.js、TypeScript、Tailwind 升级的版本兼容性
references/staged-upgrades.md	Codemod 自动化、自定义迁移脚本、对等依赖处理、工作区升级
references/testing-strategy.md	完整的测试金字塔、CI 集成、包体积分析、性能测试

模板文件

templates/ 中提供了可直接使用的配置文件：

模板	用途
npmrc-security.tmpl	禁用脚本并设置冷却期的安全 .npmrc
bunfig-security.tmpl	设置冷却期和排除项的安全 bunfig.toml
pnpm-workspace-security.tmpl	设置冷却期、allowBuilds 和 trustPolicy 的安全 pnpm-workspace.yaml
yarnrc-security.tmpl	设置版本准入期和预批准软件包的安全 .yarnrc.yml
dependabot-security.tmpl	带有 7 天冷却期的 Dependabot 配置
renovate-security.tmpl	带有 minimumReleaseAge 和自动合并规则的 Renovate 配置
devcontainer-security.tmpl	带有安全选项的加固开发容器
socket-fix-ci.tmpl	GitHub Actions：Socket Fix 自动修复工具，可按冷却期同步修复 CVE
socket-scan-ci.tmpl	GitHub Actions：每次推送或 PR 都会运行的 Socket CI 安全门禁