| name | release-please-flow |
| description | 使用 Google release-please 的通用发版流程。
当用户说"发版"时触发。处理源分支→main 合并后 release-please 自动创建发版分支、
prepareRelease、本地 CI 模拟验证、用户二次确认后最终合并发版。
支持 dev→main、hot-fix→main 等场景。
|
release-please 发版流程
概述
使用 Google release-please 自动管理版本号。机器人读取 main 分支 git 历史中的
conventional commits 自动决定版本号（major/minor/patch）。绝对不要手动指定版本号。
为什么最后一步极其危险
- npm 版本号不可重发：同版本号一旦发布，即使删除 npm 包该版本号也永久占用
- release-please 基于 git tag 判断：跳过或发错的版本号永远空缺，无法填补
- 发错版本只能接受：比如误升 major，只能继续往下发，不能回退
- CHANGELOG 一旦推到 main 就写入历史：修正需要 force push main，极度危险
- 合并发版分支到 main = 按下发射按钮：CI 自动触发 npm publish，不可撤销
场景 A：日常发版（dev → main）
-
用户说"发版"
-
合并 dev 到 main：
git checkout main
git merge dev --no-edit
git push origin main
-
release-please CI 检测到 main 更新，自动创建发版分支：
release-please--branches--main--components--<package-name>
-
切换到发版分支：
git fetch origin
git checkout release-please--branches--main--components--*
-
运行 prepareRelease：
pnpm prepareRelease
-
提交（版本号由 release-please 自动决定，禁止手动指定）：
git add -A
git commit -m "chore(main): release X.Y.Z"
⚠️ 此时不要 push
-
本地 CI 模拟（push 前验证一切正常）：
pnpm install && pnpm run build && pnpm run test
- 构建失败 → 修好再继续
- 测试失败 → 修好再继续
- 全部通过 → 进入下一步
-
版本号二次验证（push 前最后检查）：
cat .release-please-manifest.json
cat CHANGELOG.md | head -10
git log --oneline -3
特别注意：全是 fix 提交不应升 major，全是 feat 不应只升 patch
-
报告用户 review，输出以下信息：
- 版本号
- 构建结果（通过/失败）
- 测试结果（通过/失败）
- CHANGELOG 预览
- "以上确认无误后，告诉我可以 push 和合并"
-
用户确认后，push 发版分支：
git push origin <release-please-branch-name>
-
⚠️ 最终合并由用户亲自操作：合并发版分支到 main = 触发 npm publish。
我只能提醒你 review，你自己点合并按钮。
一旦合并，版本号永久生效，不可回退、不可跳过、不可重用。
-
合并完成后，手动删除发版分支（bot 不会自动删除）：
git branch -d <release-please-branch-name>
git push origin --delete <release-please-branch-name>
场景 B：紧急修复发版（hot-fix → main）
流程同场景 A，把 dev 换成 hot-fix 分支即可。也是一次性的。
场景 C：其他分支 → main
流程同场景 A，替换源分支名称。
关键规则
- 绝对不要手动指定版本号 — release-please 自动处理
- 绝对不要在用户确认前合并到 main — 合并即发版
- 本地 CI 模拟是必须的 — 不通过不能 push
- 版本号验证是必须的 — 检查 bump 类型是否匹配提交内容（如全是 fix 不应升 major）
pnpm prepareRelease 会执行：
pnpm syncVersion — 同步根 package.json 版本号到所有子包pnpm parseChangelog — 解析 CHANGELOG.md
- Conventional commits 决定版本号类型：
fix: → patch（x.y.Z）feat: → minor（x.Y.0）feat!: 或 BREAKING CHANGE: → major（X.0.0）
常见坑
- release-please 误升主版本：main 提交历史中有残留的
BREAKING CHANGE footer，会导致误升 major 版本。用 git log 检查所有未被 release 的提交 body 是否不应含 breaking change
- CI 里
packageManager 字段控制 pnpm 版本：不要在 CI workflow 里硬编码 version:
- pnpm 10+ 封锁 lifecycle scripts：确保
package.json 里有 pnpm.onlyBuiltDependencies
- vite-plugin-static-copy 在 Vite 7 下不可靠：用自定义
closeBundle 插件替代
