用 Claude Code 安全管理 Changesets 版本发布

Claude Code 能让发布工作快很多，但版本号不能交给 AI 随手判断。把破坏性修改发布成 patch，会让下游项目突然构建失败；把内部 package 发布到 npm，清理成本也很高。Changesets 的价值在于把“为什么要发布、哪个 package 要升哪个版本”写进 PR，而不是事后猜测。

本文以实际工程为目标：SemVer 基础、package release notes、monorepo package、private/internal package、GitHub Actions release flow、npm publish 风险、CHANGELOG 质量，以及如何避免 AI 生成错误的版本升级。官方资料建议同时参考 SemVer、Changesets、npm 发布文档 和 GitHub Actions 文档。站内延伸可以看 CLAUDE.md 最佳实践、CI/CD 设置 和 monorepo 管理。

先把 SemVer 说清楚

SemVer 是 semantic versioning，也就是“有语义的版本号”。1.4.2 从左到右是 major.minor.patch。patch 用于不改变公开接口的修复，minor 用于向后兼容的新功能，major 用于可能要求用户改代码的破坏性变化。这里的“公开接口”不只是函数名，也包括 React props、CSS token、CLI flag、默认行为、导出的 TypeScript 类型。

Changesets 会把发布意图写入 .changeset/*.md，再根据这些文件生成 version、CHANGELOG、release PR 和 publish。Claude Code 适合做 diff 阅读、changeset 草稿、风险检查，但不应该在没有规则的情况下直接改 package.json 的 version。

常见用例有四类：

用例	版本风险	Claude Code 可检查内容
UI package	props、variant、CSS token、peer dependency	bump 是否符合公开 API 变化
CLI package	命令名、flag、退出码	README、测试和实现是否一致
monorepo	workspace 依赖范围	依赖 package 是否也需要发布
内部 package	误发到公开 npm	private、ignore、registry、token

初始化 Changesets

先安装并初始化。

npm install -D @changesets/cli @changesets/changelog-github
npx changeset init

.changeset/config.json 可以从这个配置开始：

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

fixed 表示一组 package 永远保持同一个版本。linked 表示相关 package 一起 bump，但保留各自版本号。updateInternalDependencies 决定 workspace 内部依赖怎么更新。这个设置在 monorepo 里很重要，因为本地 workspace:* 能跑，不代表发布后用户环境也能解析。

package scripts 建议固定下来，避免每个人或每次 AI 输出使用不同命令。

{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status --since=origin/main",
    "version": "changeset version",
    "release": "changeset publish",
    "build": "tsc -p tsconfig.json",
    "test": "vitest run"
  }
}

写 changeset 文件

每个影响公开 package 的 PR 都运行：

npx changeset

示例 changeset：

---
"@myapp/ui": minor
"@myapp/utils": patch
---

Add the `outline` variant to Button and keep the existing `solid` and `ghost` variants compatible.

Fix `formatCurrency` so it handles zero-decimal currencies without rounding errors.

这里 @myapp/ui 是向后兼容的新功能，所以是 minor；@myapp/utils 是修复已有函数，所以是 patch。如果删除了 variant="primary"、重命名 CLI flag、改变默认行为，就要按 major 候选处理。

给 Claude Code 的提示词应当写成审查任务：

读取当前 PR diff，并草拟 Changesets changeset。

规则:
- 遵守 SemVer: 破坏性变化 major，向后兼容功能 minor，修复 patch
- 不要直接修改 package.json 的 version
- 不要执行 npm publish
- 不要把 private: true 的 package 放入发布计划

输出:
- 变更的 package 列表
- 每个 package 的推荐 bump
- 推荐理由
- .changeset/*.md 内容草稿
- 需要人工判断的不确定点

monorepo 与内部 package

真实仓库常常同时包含可发布 package 和不会发布的 app。例如 @myapp/ui 发布到 npm，而 @myapp/app 只部署到生产环境。内部 app 要明确标记：

{
  "name": "@myapp/app",
  "private": true,
  "version": "0.0.0",
  "scripts": {
    "build": "next build"
  },
  "dependencies": {
    "@myapp/ui": "workspace:*"
  }
}

Changesets 里也可以把非发布对象放进 ignore：

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [
    ["@myapp/core", "@myapp/cli"]
  ],
  "linked": [
    ["@myapp/ui", "@myapp/theme"]
  ],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myapp/app", "@myapp/docs"]
}

如果发布到公司内部 registry，要把 registry 写在 package 里，并和公开 npm token 分开。

{
  "name": "@my-company/internal-kit",
  "version": "1.8.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com",
    "access": "restricted"
  }
}

GitHub Actions 发布流程

changesets/action 可以创建 version PR，并在 PR merge 后发布。发布 job 要先跑 test 和 build。

name: Release

on:
  push:
    branches:
      - main

concurrency: release-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm test
      - run: npm run build

      - name: Create release PR or publish to npm
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

PR 阶段加一个 changeset 检查：

name: Changeset Check

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  changeset:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx changeset status --since=origin/main

文档或测试专用 PR 可以不需要 changeset，但 skip 条件必须由团队规则定义。不要让 Claude Code 在修复 CI 时随手加入宽松的 skip。

提升 CHANGELOG 质量

差的 release note 通常像这样：

---
"@myapp/ui": minor
---

Update Button.

更好的写法要说明影响和迁移：

---
"@myapp/ui": minor
---

Add `variant="outline"` to `Button`.

Existing `solid` and `ghost` variants keep the same props and class names. Teams using a custom theme should add `--button-outline-border` only if they want to override the default border color.

让 Claude Code 做批判性 review：

请把下面的 changeset 当作公开 CHANGELOG 进行审查。

检查:
- 用户能否理解影响范围
- 文本是否匹配 major/minor/patch 判断
- 需要 migration 时是否有步骤
- 是否用“更新”“优化”替代了具体说明
- package、函数、props 名是否真实存在

可疑点请列成问题，不要默默改写。

常见失败模式

第一，直接说“帮我升版本”。Claude Code 可能只改 package.json，没有 changeset。正确做法是先生成 changeset，再由 release PR 执行 changeset version。

第二，把破坏性变化当成 minor。TypeScript 类型变化也可能破坏用户构建。删除 export、改 props、改 CLI flag、改默认行为都要重点检查。

第三，误发布内部 package。private: true、ignore、publishConfig.registry、CI token 权限和 npm pack --dry-run 要一起看。

第四，漏掉内部依赖 bump。@myapp/core 变了，依赖它的 @myapp/cli 可能也需要发布，否则用户会拿到不一致的组合。

本地验证

发布前运行：

npm run changeset:status
npm test
npm run build
npm run version -- --snapshot canary
git diff -- package.json package-lock.json pnpm-lock.yaml yarn.lock CHANGELOG.md
npm pack --dry-run

snapshot 用来检查版本计算和 CHANGELOG，不用于正式发布。npm pack --dry-run 可以看到 tarball 内容，适合检查 .env、大型 fixture、内部文档、缺失的 build 产物。

变现与团队导入

稳定的 release flow 会影响收入。UI kit、CLI、SDK、模板 package 如果能可靠发布，就可以连接付费模板、企业培训、内部平台建设和顾问服务。反过来，错误的版本号和空泛的 CHANGELOG 会迅速损害信任。

如果要把这套流程落到真实仓库，可以从 Claude Code 培训与咨询 开始，把 Changesets、CLAUDE.md、GitHub Actions、npm token 权限、release review prompt 和 monorepo package policy 一起设计。

实测结果

我用一个小型 npm workspace 的流程核对了本文内容：初始化 Changesets、创建 changeset、运行 changeset status、设计 release PR、检查 publish guardrail。Claude Code 很适合根据 diff 起草 release note，但单独判断 SemVer 不够稳定。让它解释“为什么这不是破坏性变化”，更容易发现错误的 minor 或 patch 判断。