GitHub 原生 Stacked PR 上手教程：gh stack 命令怎么用、怎么合并、老分支怎么转
GitHub 原生 Stacked PR 上手教程：gh stack 命令怎么用、怎么合并、老分支怎么转
先把搜索者最常问的几件事直接说清：
- 这是什么：Stacked PR（堆叠式 PR）= 把一个大改动拆成一串有依赖顺序的小 PR，每个 PR 只含自己那一层的 diff，逐层评审，最后可以一键把整串合入。
- 什么时候上线的：GitHub 于 2026 年 7 月 30 日将其作为原生功能开启公测（public preview），逐步推送到所有仓库——在此之前你只能靠 Graphite、spr、git-branchless 这类第三方工具模拟。
- 收费吗：不收费，不是付费计划专属功能。CLI 扩展
gh-stack免费安装。 - 在哪用：github.com 网页、
gh命令行、GitHub 移动端都支持；还有配套的 AI agent skill。
一、五分钟上手：从零建一个 stack
前提：装好 GitHub CLI（v2.0+，Windows/macOS/Linux 都有官方安装包），然后装官方扩展：
gh extension install github/gh-stack
核心心智模型：一个 stack 是一列有序分支，每层建立在下一层之上，最底层基于主干（通常是 main）：
frontend → PR #3 (base: api-endpoints) ← 顶层
api-endpoints → PR #2 (base: auth-layer)
auth-layer → PR #1 (base: main) ← 底层
─────────────
main (trunk)
完整流程：
# 1. 建 stack（创建并切到第一个分支）
gh stack init
# ...在第一层提交代码...
# 2. 在上面叠一层
gh stack add api-endpoints
# ...继续提交...
# 3. 推送所有分支
gh stack push
# 4. 查看整个 stack
gh stack view
# 5. 一次性开出整串 PR（每层一个，base 自动指向下一层）
gh stack submit
submit 之后，GitHub 会把这串 PR 链接成一个 Stack 对象：每个 PR 页面顶部出现 stack map，评审者能看到当前层在整串改动中的位置，且每个 PR 只显示本层的 diff。
一个顺手的技巧：gh stack add -Am "Add login endpoint" 可以一条命令完成"暂存全部改动 + 提交 + 自动按日期生成分支名 + 叠新层"。
二、评审与合并：最关键的三条规则
- 各层可以并行评审。不同同事评不同层互不阻塞，这正是它对"AI 时代 PR 越来越大"这个痛点的解法。官方公告里 TED 的 CTO 说得直白：AI 让开发者产出暴涨后，评审成了新瓶颈，把大改动拆成有依赖顺序的小块后，"评审不只是更快了，而是更准了"。
- 可以只合并其中一部分。合并一个或几个下层 PR，上面的 PR 会保持打开，并自动 rebase 和重定向 base（比如 PR #1 合入 main 后，PR #2 的 base 自动改成 main）。
- 也可以一键合并整串。合并最上面一个"ready"的 PR，它和下面所有未合并的层会一次性全部落地。分支保护和 required checks 依旧生效，管的是最终进入
main的内容。
Merge queue（合并队列）对 stack 的支持在公测后数周内逐步推送——重度依赖 merge queue 的团队用前先确认自己仓库已生效。
三、已有的分支/PR 怎么转成 stack
不用重来。gh stack init 支持采纳现有分支：
# 把两个已存在的分支按顺序收编成一个 stack
gh stack init feature-auth feature-api
# 主干不是 main？指定 trunk
gh stack init --base develop feature-auth
同事的 stack 也可以直接拉下来接着干：
gh stack checkout 42 # 按 PR 号
gh stack checkout <PR URL> # 按 PR 链接
gh stack checkout # 交互式选择器，列出本地+远端所有 stack
四、日常维护：rebase 与 sync
底层改了、main 前进了，上面各层怎么跟上？两个命令：
# 拉取远端 + 从主干向上逐层级联 rebase
gh stack rebase
# 一条命令完成：拉取、对齐远端 stack、级联 rebase、推送、同步 PR 状态
gh stack sync
细节上官方想得比较周到：init 时自动开启 git rerere（冲突解法会被记住，跨层 rebase 不用反复解同一个冲突）；rebase 冲突时会打印冲突文件和行号，解完 git add 后 gh stack rebase --continue，想整体撤销用 --abort 一键回到 rebase 前状态；某层 PR 已被合并时，rebase 自动切换 --onto 模式正确重放提交。
stack 的元数据存在本地 .git/gh-stack（JSON 文件，不入库）。
五、常见问题 FAQ
Stacked PR 是付费功能吗？
不是。公测阶段逐步推送到所有仓库，CLI 扩展免费。
能只合并 stack 里的一个 PR 吗？
能，方向有讲究：合并下层，上层自动 rebase 重定向、保持打开；合并上层，它下面所有未合并的层会一起落地。想逐个落地就从最底层开始合。
Windows 上能用吗？
能。gh CLI 官方支持 Windows/macOS/Linux，gh-stack 通过 gh extension install 跨平台安装，命令行为一致。
网页上能建 stack 吗，还是必须用命令行？
官方口径是 stack 可以在 github.com、CLI 和移动端上操作：网页流程是先开第一个 PR，再在其上叠加分支和 PR（每个 PR 的 base 指向下一层）。命令行的 init/add/submit 是效率最高的路径。
和 Graphite、spr 这类第三方工具比呢？
最大差异是原生：stack map 直接长在 PR 页面里、分支保护/required checks/merge queue 官方打通、评审者不需要装任何东西。第三方工具多年来填的坑（级联 rebase、base 自动重定向）现在是平台内置行为。
AI 编码代理能用它吗？
官方发布了配套 skill：gh skill install github/gh-stack，装完你的 AI agent（如 Copilot、Claude Code）就知道如何用 gh stack 全套命令管理堆叠 PR。
什么时候正式 GA？
官方未公布时间表，目前是 public preview，功能可能变化。反馈渠道是官方 stacks discussion（gh.io/stacks-feedback）。