dep-lib-review

依赖项审查

触发条件

在以下情况下运行此审查：

• 每月维护周期
• 主要版本发布或分支冻结前
• CI 中的 pnpm audit 报告漏洞
• 主要生态库（React、Vite、TypeScript 等）发布新主版本

步骤 1 — 收集当前状态

并行运行：

# Outdated packages (name, current, wanted, latest)
pnpm outdated 2>/dev/null || true

# Security vulnerabilities (runtime + dev)
pnpm audit --json 2>/dev/null | jq '
  .vulnerabilities | to_entries[] |
  { name: .key, severity: .value.severity,
    isDirect: .value.isDirect,
    via: [.value.via[] | select(type=="object") | .title] }'

# Check if Renovate / Dependabot is configured
ls .github/renovate.json renovate.json .github/dependabot.yml 2>/dev/null || echo "no bot configured"

如果已配置机器人（Renovate/Dependabot），先检查其尚未处理的 PR，避免重复工作。

步骤 2 — 分类处理

安全问题

不要只看 CVSS 评分。要考虑攻击向量的权重：

CVE 类型	仅 devDep	浏览器 SPA	SSR / Edge
RCE	忽略	忽略	P0
通过库实现的 XSS	忽略	P0	P0
原型污染	忽略	P1（检查输入路径）	P0
ReDoS	忽略	P1（检查用户输入是否可达）	P0
供应链（postinstall）	P0	P0	P0
路径遍历 / SSRF	忽略	忽略	P0

# Exclude devDeps to focus on runtime CVEs
# Fallback to plain text if jq parsing fails (pnpm JSON schema varies by version)
pnpm audit --prod --json 2>/dev/null | jq -r '
  .vulnerabilities | to_entries[] |
  .value.via[] | select(type=="object") |
  "\(.severity)\t\(.name)\t\(.title)"' 2>/dev/null | sort -k1 \
  || pnpm audit --prod 2>/dev/null

版本更新 — 批量处理策略

更新类型	策略
补丁版（1.2.3 → 1.2.4）	全部合并到一个 PR 中。无需阅读变更日志。
次要版本（1.2.x → 1.3.x）	检查变更日志中是否有弃用项。将不含破坏性变更的更新合并处理。
主版本（1.x → 2.x）	每个包单独创建一个 PR。阅读迁移指南。绝不要与其他变更合并处理。

确定每个过时包的类别：

# Categorize outdated packages (deprecated / major / minor / patch)
pnpm outdated --json 2>/dev/null | jq -r '
  to_entries[] |
  (.value.current // "none") as $cur |
  (.value.latest // "none") as $lat |
  (.value.dependencyType // "dependencies") as $t |
  ($cur | split(".")[0]) as $curMaj |
  ($lat | split(".")[0]) as $latMaj |
  (if .value.isDeprecated then "deprecated"
   elif $curMaj != $latMaj then "major"
   elif ($cur | split(".")[1]) != ($lat | split(".")[1]) then "minor"
   else "patch" end) as $category |
  "\($category)\t\(.key)\t\($cur) → \($lat)\t\($t)"' | sort

趋势观察（手动检查）

标记所有符合以下情况的包：

• jest → 迁移到 vitest
• axios → 迁移到 fetch / ky
• moment → 迁移到 Temporal / date-fns / 原生 Date
• lodash → 替换为原生 Array/Object API
• webpack → 迁移到 Vite
• mocha/chai → 迁移到 vitest
• ESM 项目中仅支持 CJS 的包（检查其 package.json 中的 exports 字段）
• 标记为弃用的 @types/<pkg> → 基础包现在很可能已自带类型。验证方式：cat node_modules/<pkg>/package.json | jq '.types, .typings'。如果结果非 null，则移除 @types/<pkg> 这一 devDep — 无需任何迁移成本。

步骤 3 — 执行更新

补丁版 + 安全的次要版本更新

# Update all packages to their "wanted" semver range
pnpm update

# Validate
pnpm typecheck && pnpm test:ci && pnpm lint

如果项目有 E2E 测试：

pnpm test:e2e

作为一个 PR 提交：chore: update patch/minor dependencies。

主版本更新（每次更新一个包）

# Update single package to latest
pnpm add <package>@latest

# For devDep
pnpm add -D <package>@latest

然后：

1. 阅读官方迁移指南 / CHANGELOG，了解破坏性变更。
2. 检查是否存在官方 codemod（例如 @tailwindcss/upgrade、React codemods）。先运行它 — 它可以自动处理约 80-90% 的机械性变更。
   • 运行 codemod 后，检查 package.json 中是否有依赖项位置错误：有些 codemod 会将构建时所需的包加入 dependencies，而不是 devDependencies。如有需要，将其移至正确位置。
   • 涉及复杂插件时，codemod 可能无法完成全部迁移。检查输出日志中是否有“无法自动迁移”的警告，并手动处理。
3. 运行 grep -r "deprecated API" src/ 或使用 ast-grep 查找变更后的 API。
4. 修复所有问题。
5. 验证：pnpm typecheck && pnpm test:ci && pnpm lint。
6. 如果存在 VRT 快照，涉及 UI 的升级后要在 Linux 容器中重新生成快照。
7. 作为独立 PR 提交：chore: upgrade <package> to v<N>。

pnpm 主版本升级故障排查

如果编辑 package.json 后 pnpm install 失败：

错误	原因	修复方法
ERR_PNPM_MISSING_TIME	pnpm store 中的元数据过期	运行 pnpm store prune 后重试
注册表中存在的包出现 ERR_PNPM_NO_MATCHING_VERSION	过时的锁文件条目与新的传递依赖冲突	删除 pnpm-lock.yaml，然后运行 pnpm install 重新解析依赖

删除锁文件后，在同一个 PR 中与 package.json 变更一起提交新锁文件。

步骤 4 — 验证清单

将 PR 标记为就绪前：

• pnpm typecheck 通过
• pnpm test:ci 通过
• pnpm lint 通过
• pnpm build 成功（包体积回归不超过 5%）
• E2E 冒烟测试通过（如适用）
• pnpm audit 未发现高危/严重问题（或所有剩余问题均已分类处理）

第 5 步 — 输出

撰写简要摘要，包含：

## Dependency review — <YYYY-MM-DD>

### Security
- [FIXED] <package>@<ver>: <CVE title> (was <severity>)
- [IGNORED] <package>: <reason> (devDep-only / browser-only / no user input path)

### Updated
- Patch batch: <N> packages → see commit <sha>
- Major: <package> v<old> → v<new> (standalone PR #<N>)

### Deferred
- <package> v<old> → v<new>: migration effort high, scheduled for <date>

### Trend watch
- <package>: migration recommended → <alternative>

反模式

• 将主要版本升级捆绑在一起——一个回归问题就会导致整个批次无法测试
• 盲目接受 pnpm audit fix --force——它可能会悄无声息地跳过主版本
• 忽略 CVE，却不记录分类处置原因
• 将 @types/* 包与其对应的运行时包分开更新——务必同步更新

相关内容

• frontend-review-deps — 扩展版本，包含用于 frontend-review 套件的脚本（CVE 分类处置 + 趋势监控数据文件）
• upstream-fix-and-pin — 当修复需要通过修补上游来实现时使用