dependency-upgrade

依赖升级

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

何时使用此技能

• 升级主要框架或库的版本
• 配置供应链攻击防护（冷却期、脚本拦截、锁文件加固）
• 设置安全的包管理器配置
• 解决依赖冲突或对等依赖问题
• 规划包含测试的增量升级路径
• 使用 Renovate、Dependabot 或 Snyk 自动执行依赖更新
• 审计依赖项中的漏洞
• 设置 CI/CD 依赖安全工作流

两种操作模式

交互式 — 逐步回答设置问题，以生成量身定制的配置。适用于全新设置。

默认 — 立即应用建议的默认设置：7 天冷却期、拦截所有脚本、冻结锁文件、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. 自动合并策略

选项	行为
无	所有更新均需人工审核
仅次要版本和补丁版本	自动合并安全更新，主要版本需审核
全部（需批准）	经团队批准后自动合并

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. Dev Containers — 生成加固后的 .devcontainer/devcontainer.json（是/否）

10. Secrets Manager — 1Password CLI / Infisical / 无

11. pnpm Trust Policy — 启用 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. 逐步升级 — 每次只升级一个主版本，并在每次升级后进行测试
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 内置了 21 天的升级 PR 冷却期，无需配置。

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 集成和 bundle 分析。

回滚计划

#!/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
• 未在每次单独升级后进行测试
• 忽略 peer 依赖警告
• 忘记更新或提交锁文件
• 未阅读变更日志中的重大变更说明
• 跳过主版本，而不是逐步升级
• 没有回滚计划
• 轻信 npmjs.org 上显示的源代码（它可能与实际 tarball 不同）
• 未禁用安装后脚本（这是最常见的攻击途径）
• 未为新软件包版本设置冷却期

何时加载参考资料

当用户需要超出 SKILL.md 快速参考范围的详细信息时，加载以下参考文件：

加载此文件	适用场景
references/cooldown-config-guide.md	为特定包管理器配置冷却期、集成 CI 工具或设置排除模式
references/package-manager-security.md	查看完整的各包管理器加固指南，包括 pnpm 信任策略、blockExoticSubdeps 和跨包管理器速查表
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 安全门禁