GitHub Pull Request 指南：从 Fork 到 Merge 的图文实战教程

GitHub Pull Request 指南：从 Fork 到 Merge 的图文实战教程

Pull Request（简称 PR）是 GitHub 协作开发的核心机制，也是每一位开发者参与开源项目或团队协作的必备技能。很多新手第一次提交 PR 时总会遇到各种问题：Fork 之后怎么同步？分支怎么命名？PR 描述该写什么？冲突了怎么办？

本文将通过图文并茂的方式，带你完整走一遍 PR 的全流程，掌握从 Fork 代码到合并入库的每一个细节。

一、什么是 Pull Request？

Pull Request 直译是"拉取请求"，简单来说就是：你在自己的分支上修改代码后，请求项目维护者将你的改动合并到主分支中。

在这个过程中，团队成员可以查看你的代码、提出修改意见、讨论问题，最终确认无误后才会合入代码库。PR 就像一道代码质量的"安检门"，确保每一行进入主干的代码都经过审核。

PR 的核心价值

• 代码质量保障：多人审核机制，减少 Bug 流入主干
• 知识共享：团队成员可以互相学习代码风格和实现思路
• 历史追溯：完整记录每次改动的原因、讨论过程和修改轨迹
• 安全隔离：在独立分支开发，不影响主分支的稳定性

二、PR 完整操作流程（图文详解）

第一步：Fork 目标仓库（外部贡献者）

如果你不是项目的直接成员，没有仓库的写权限，第一步需要 Fork 仓库到自己的账号下。

打开目标仓库主页，点击右上角的 Fork 按钮：

在这里插入图片描述

稍等片刻，仓库就会完整复制到你的 GitHub 账号中。

💡 小提示：团队内部协作如果有写权限，可以直接在原仓库创建分支，跳过 Fork 步骤。

第二步：克隆仓库到本地

将你 Fork 后的仓库克隆到本地进行开发：

git clone https://github.com/你的用户名/仓库名.git
cd 仓库名

为了后续能同步原仓库的最新代码，建议添加上游仓库地址：

git remote add upstream https://github.com/原作者/仓库名.git

可以通过 git remote -v 查看是否配置成功，你应该看到：

• origin：指向你的 Fork 仓库
• upstream：指向原始官方仓库

第三步：创建开发分支

重要原则：永远不要直接在 main 分支上修改代码！

根据修改类型创建对应的分支，推荐命名规范：

创建并切换分支：

# 先拉取上游最新代码，保证基于最新版本开发
git fetch upstream
git merge upstream/main

# 创建新分支
git checkout -b feature/your-feature-name

第四步：代码修改与提交

在本地完成代码修改后，查看改动并提交：

# 查看修改了哪些文件
git status

# 查看具体修改内容
git diff

# 添加修改到暂存区
git add .

# 提交代码（写清楚提交信息）
git commit -m "feat: add user login functionality"

📝 提交规范：建议遵循 Conventional Commits 规范：type: description，方便自动生成变更日志，也让审核者一眼看懂改动类型。

第五步：推送分支到 GitHub

将本地分支推送到你的远程仓库：

git push origin feature/your-feature-name

推送成功后，回到 GitHub 仓库页面，你会看到一个黄色提示条，显示你的分支最近有推送：

在这里插入图片描述

点击绿色的 Compare & pull request 按钮，进入 PR 创建页面。

如果没有看到提示条，也可以手动切换到你的分支，点击 Contribute → Open pull request。

第六步：创建 Pull Request

现在来到了最关键的一步——填写 PR 信息。

在这里插入图片描述

页面上需要确认两个分支：

• base repository：目标仓库（原仓库）
• base：目标分支（通常是 main 或 develop）
• head repository：你的仓库
• compare：你的开发分支

确认分支无误后，填写以下信息：

1. PR 标题

简明扼要地概括这次改动，例如：

• ✅ feat: add user profile page
• ✅ fix: resolve null pointer exception in login
• ❌ update code（太模糊，审核者不知道改了什么）

2. PR 描述

详细说明改动内容，建议包含：

• 背景：为什么要做这个改动？解决了什么问题？
• 方案：大致是怎么实现的？
• 测试：做了哪些测试？结果如何？
• 关联 Issue：如果有对应的 Issue，写上 Closes #123，合并后会自动关闭 Issue

可以使用 Markdown 格式，添加截图、代码片段等辅助说明。

3. 其他选项

• Reviewers：指定审核人员
• Labels：添加标签（如 bug、enhancement）
• Projects：关联项目看板
• Milestone：关联里程碑

填写完成后，点击绿色的 Create pull request 按钮，PR 就创建成功了！

第七步：代码审核与修改

PR 创建后，项目维护者会收到通知并开始审核。他们可能会：

• 留下评论，提出疑问或建议
• 直接 Approve（批准）
• Request changes（要求修改）

如果需要修改，不需要重新创建 PR，只需要在本地同一分支继续修改，提交后推送即可：

git add .
git commit -m "fix: address review comments"
git push origin feature/your-feature-name

新的提交会自动追加到同一个 PR 中，审核者可以看到更新后的代码。

第八步：合并 PR

当 PR 获得批准，并且所有 CI 检查都通过后，就可以合并了。

通常由项目维护者点击 Merge pull request 按钮。GitHub 提供三种合并方式：

合并完成后，可以删除你的功能分支，保持仓库整洁。

三、PR 最佳实践

1. 保持 PR 小而精

一个 PR 只解决一个问题，避免"大杂烩"式的巨型 PR。几百行代码的 PR 审核效率远高于几千行的 PR。小 PR 更容易被理解、更容易测试、出问题也更容易回滚。

2. 写好 PR 描述

审核者不应该靠猜来理解你的改动。说明"为什么这么做"比"做了什么"更重要，提供充足的上下文能大幅提升审核速度。好的 PR 描述应该让不熟悉背景的人也能快速理解改动意图。

3. 提交前自测

确保代码能正常编译、所有测试通过、符合项目代码规范。不要把审核者当测试员，提交前跑一遍 lint 和单元测试是基本素养。

4. 及时响应审核

收到审核意见后尽快回复和修改，拖延会让 PR 失去上下文，增加合并难度。如果暂时没时间处理，可以留言说明情况。

5. 善用 Draft PR

如果工作还没完成，但想提前征求意见，可以创建 Draft Pull Request，标明"尚未完成，勿合并"。这样既可以提前获得反馈，又不会误导维护者。

6. 关联 Issue

每个 PR 最好都有对应的 Issue，先有问题讨论，再有代码实现。在描述中用 Fixes #编号 或 Closes #编号 关联，合并后自动关闭 Issue。

四、常见问题

Q: 合并冲突了怎么办？ A: GitHub 会在 PR 页面提示冲突文件。你需要在本地拉取目标分支的最新代码，手动解决冲突后重新推送：

git fetch upstream
git checkout feature/your-branch
git merge upstream/main
# 手动解决冲突后
git add .
git commit
git push origin feature/your-branch

Q: 可以撤回 PR 吗？ A: 可以关闭 PR，也可以随时追加新的提交来更新。关闭的 PR 也可以重新打开。

Q: 审核一直没人理怎么办？ A: 可以在评论里 @ 相关人员，或者检查 PR 是否清晰、是否有未解决的问题。也可以看看项目的贡献指南，了解预期的响应时间。

Q: 可以修改已经提交的 PR 吗？ A: 完全可以。只要在同一个分支上继续提交并推送，新的改动会自动出现在 PR 里。

五、总结

Pull Request 不仅是一个技术操作，更是一种协作文化。它代表着对代码的敬畏、对团队的尊重，以及持续改进的态度。

掌握 PR 的完整流程，你就可以顺畅地参与任何 GitHub 上的开源项目，或者在团队中建立起规范的代码审核机制。从 Fork 到 Merge，每一步都有讲究，但核心始终是——清晰的沟通 + 高质量的代码。

希望这篇教程能帮助你顺利提交第一个 PR。开源世界欢迎每一位贡献者，你的每一行代码都可能让项目变得更好。