用 Claude Code 安全管理依赖：npm、pnpm、Yarn 与 CI

依赖管理不是“全部升到最新版”

JavaScript/TypeScript 项目真正难维护的地方，往往不是自己写的几千行代码，而是背后的依赖树。React、Vite、TypeScript、ESLint、测试工具、UI 包、支付 SDK、日志库、构建插件，直接依赖加上间接依赖，很快就会变成几百个包。

Claude Code 在这里很有用，但不要把它当成自动执行 npm install xxx@latest 的按钮。更安全的用法是：先让它识别当前包管理器和 lockfile，再分类 patch、minor、major 更新，查看漏洞审计结果，生成或审查 Renovate/Dependabot PR，最后用 CI 证明更新可复现。

lockfile 是“这次实际安装了哪些版本”的记录。npm 使用 package-lock.json，pnpm 使用 pnpm-lock.yaml，Yarn 使用 yarn.lock。package.json 描述允许的范围，lockfile 记录最终解析出的精确版本和完整性信息。CI 的责任是验证这个结果，而不是悄悄重写它。

如果你还需要 CI 的整体设计，可以继续阅读 Claude Code CI/CD 设置；如果仓库是 workspace 或 monorepo，可以配合 pnpm workspace 指南 一起看。

---

推荐的工作流

依赖更新可以拆成五步：扫描、计划、更新 PR、CI、人工合并。Claude Code 最适合参与扫描、计划和 PR 审查。

flowchart LR
  scan["扫描\noutdated / audit"] --> plan["计划\npatch / minor / major"]
  plan --> pr["更新 PR\nRenovate / Dependabot"]
  pr --> ci["CI\ninstall / test / build"]
  ci --> review["Claude Code 审查\n风险与证据"]
  review --> merge["人工判断\n合并或退回"]

第一次不要要求 Claude Code 修改文件，而是让它先检查现状。

claude -p "
Inspect dependency management in this repository. Do not edit files yet.
Report package manager, lockfile, outdated direct dependencies,
security audit command, scripts that must pass, and risky major updates.
Return file paths and exact commands.
"

这句话的关键是 Do not edit files yet。先盘点，再更新。对初学者来说，可以把它理解成“先做资产清单，再决定要不要换零件”。

---

npm、pnpm、Yarn 的差异

不要在同一个仓库里混用多个包管理器。不同工具的 lockfile 和 CI 命令不同，混用会让更新结果变得不可预测。

工具	lockfile	CI 安装命令	查看过期依赖	漏洞审计
npm	package-lock.json	npm ci	npm outdated	npm audit --audit-level=high
pnpm	pnpm-lock.yaml	pnpm install --frozen-lockfile	pnpm outdated --format table	pnpm audit --audit-level high
Yarn modern	yarn.lock	yarn install --immutable	yarn up -i 或 yarn up <pattern>	yarn npm audit --recursive --severity high

npm 官方文档说明，npm ci 面向 CI 等自动环境，并且当 package.json 与 lockfile 不一致时会失败。pnpm 的 --frozen-lockfile 和 Yarn 的 --immutable 也承担类似角色。原则很简单：更新 PR 可以修改 lockfile，CI 不应该临时修补 lockfile。

---

可直接复制的验证脚本

把下面的文件保存为 scripts/verify-deps.mjs。它会根据 packageManager 字段或 lockfile 判断 npm/pnpm/Yarn，然后执行固定安装、漏洞审计、typecheck、test、build。

#!/usr/bin/env node
import { existsSync, readFileSync } from "node:fs";
import { spawnSync } from "node:child_process";

function readPackageJson() {
  return JSON.parse(readFileSync("package.json", "utf8"));
}

function detectPackageManager(pkg) {
  const declared = pkg.packageManager || "";
  if (declared.startsWith("pnpm@")) return "pnpm";
  if (declared.startsWith("yarn@")) return "yarn";
  if (declared.startsWith("npm@")) return "npm";
  if (existsSync("pnpm-lock.yaml")) return "pnpm";
  if (existsSync("yarn.lock")) return "yarn";
  if (existsSync("package-lock.json")) return "npm";
  throw new Error("No package manager or lockfile detected.");
}

function run(command, args) {
  const label = [command, ...args].join(" ");
  console.log(`\n$ ${label}`);
  const result = spawnSync(command, args, {
    stdio: "inherit",
    shell: process.platform === "win32",
  });
  if (result.status !== 0) throw new Error(`Command failed: ${label}`);
}

const pkg = readPackageJson();
const manager = detectPackageManager(pkg);

const installCommands = {
  npm: ["npm", ["ci"]],
  pnpm: ["pnpm", ["install", "--frozen-lockfile"]],
  yarn: ["yarn", ["install", "--immutable"]],
};

const auditCommands = {
  npm: ["npm", ["audit", "--audit-level=high"]],
  pnpm: ["pnpm", ["audit", "--audit-level", "high"]],
  yarn: ["yarn", ["npm", "audit", "--recursive", "--severity", "high"]],
};

const scriptCommands = {
  npm: (name) => ["npm", ["run", name]],
  pnpm: (name) => ["pnpm", ["run", name]],
  yarn: (name) => ["yarn", ["run", name]],
};

run(...installCommands[manager]);
run(...auditCommands[manager]);

for (const name of ["typecheck", "test", "build"]) {
  if (pkg.scripts?.[name]) run(...scriptCommands[manager](name));
  else console.log(`\n- skip ${name}: script not found`);
}

console.log(`\nDependency verification passed with ${manager}.`);

在 package.json 中加入：

{
  "scripts": {
    "deps:verify": "node scripts/verify-deps.mjs"
  }
}

这个脚本不负责“更新”，只负责“验证”。这样 Claude Code、Renovate、Dependabot 和人工修改都必须经过同一个门槛。

---

三个常见场景

第一个场景是小型 Web 应用的 patch/minor 更新。ESLint、Prettier、Vite 插件、测试工具的 patch/minor 可以分组处理，但 major 更新不要混在一起。可以这样问 Claude Code：

claude -p "
Prepare a dependency update plan for devDependencies only.
Group patch and minor updates for lint/test/build tools.
Do not update major versions.
Run the dependency verification script after changes.
"

第二个场景是漏洞审计。不要一看到高危就执行 audit fix --force。先查看 JSON 报告，再让 Claude Code 判断它是直接依赖还是间接依赖、是否只需要刷新 lockfile、是否必须做 major 更新。

npm audit --json
pnpm audit --json
yarn npm audit --recursive --json

第三个场景是 workspace 或 monorepo。依赖管理不仅是升级外部包，也包括内部包的边界。packages/ui 不应该 import apps/web；内部包最好使用 workspace:*，否则将来可能从 registry 拉到同名包。

claude -p "
Inspect this workspace before dependency updates.
Find packages/* importing from apps/*, internal dependencies not using workspace:*,
duplicated versions of react/typescript/eslint, and scripts that should use filters.
Do not edit files.
"

---

Renovate 与 Dependabot 配置

Renovate 适合需要细分规则的团队。下面的配置把 major 更新留给人工，允许低风险开发依赖在 CI 通过后自动合并。

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "dependencyDashboard": true,
  "lockFileMaintenance": {
    "enabled": true,
    "schedule": ["before 5am on monday"],
    "automerge": true
  },
  "packageRules": [
    {
      "matchManagers": ["npm"],
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "labels": ["dependency", "major-update"],
      "automerge": false
    }
  ]
}

如果只想在 GitHub 上快速开始，可以使用 Dependabot。

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    groups:
      dev-tooling:
        dependency-type: "development"
        update-types:
          - "minor"
          - "patch"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "monthly"

Dependabot 官方文档要求使用 version: 2 和 updates，并为每个 ecosystem 指定目录与更新频率。GitHub Actions 也应该被纳入更新范围，否则工作流本身会老化。

---

CI 中的最终验证

name: dependency-check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  verify-dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: corepack enable
      - run: node scripts/verify-deps.mjs

先保证流程可复现，再考虑缓存。缓存能加速，但如果排查依赖问题时缓存状态不透明，反而会拖慢定位。

---

具体踩坑

第一，CI 里用 npm install。它可能更新 lockfile，应该改成 npm ci。第二，把 audit fix --force 当默认修复。它可能带来 major 变更。第三，把多个 major 更新放进同一个 PR。React、Vite、TypeScript、支付 SDK 这种更新应该拆开。第四，只看 package.json 不看 lockfile。lockfile 中新增的 registry、大型间接依赖、完整性变化都值得检查。第五，把开发依赖和生产依赖同等处理。lint 工具的 patch 与认证 SDK 的更新风险完全不同。

对于内容站，还要注意 MDX、CSS、构建工具更新可能影响页面、代码块和 CTA。可以参考验证收据工作流建立发布前检查。

---

PR 审查提示词

claude -p "
Review this dependency update PR.
Focus on package.json, lockfile, CI config, and test output.
Report updated packages, direct vs transitive changes, major updates,
peer dependency changes, commands that passed or failed, and manual checks.
Do not change files unless there is a blocking issue.
"

好的依赖 PR 审查应该给出证据，而不是只说“看起来没问题”。

---

官方资料与下一步

官方资料建议查看 npm ci、npm audit、pnpm install、pnpm audit、yarn install、yarn npm audit、Claude Code CLI、Dependabot options 和 Renovate automerge。

如果你想把这套流程用于团队，可以继续看 CLAUDE.md 最佳实践 和 Claude Code 安全审计。需要把实际仓库的更新规则、CI、审查提示词和漏洞响应流程固定下来时，可以通过培训与咨询继续推进。

实际试用结果

我用 Node.js 22、npm、pnpm 和现代 Yarn 的思路整理了这个流程。最有效的变化是把“生成更新”和“验证更新”分开：Claude Code 可以帮你做计划和审查，但所有更新都必须通过同一个 deps:verify。同时，major 更新不自动合并、每次都检查 lockfile 差异，会显著减少依赖更新带来的噪音。