第5篇：Pull Request：邀请别人“审查作业”——优雅地合并代码，保证质量
📝 场景引入
小白：“我在 "feature-blog" 分支里把博客功能做好了，怎么把它放进 "main" 里？直接把文件复制过去吗？” 爱好者：“千万别！那样会丢掉所有的提交记录和历史。你需要 Pull Request（PR）——像交作业一样提交你的代码，请人帮你检查，然后优雅地合并。” 真实痛点：
- 直接合并分支，不小心引入了bug，却不知道是谁、哪次提交造成的
- 自己没发现的错误，别人一眼就能看出来
- 想把多个人的修改有条理地整合在一起
PR 就是 Git 协作的“质检关卡”。
📥 核心概念（比喻版）
什么是 Pull Request？
想象你在写小组论文：
- 分支 = 你负责的那一章草稿
- main 分支 = 最终要交的完整论文
- Pull Request = 提交草稿给组长审阅
- 你说：“我写完了这一章，请帮我看看”
- 组长检查：格式对不对？内容有没有矛盾？
- 没问题 → 批准并入最终论文
- 有问题 → 打回来让你修改
Gitee 的 PR 同理：
“嗨，我把新功能做在这个分支里了，请审查一下，没问题的话就合并进主分支吧。” 为什么必须用 PR？
- 质量控制：有人帮你挑错，减少 bug
- 知识共享：别人知道你做了什么，怎么做的
- 历史清晰：每一个合并都有据可查，可追溯
- 讨论记录：关于这段代码的所有讨论都保存在 PR 里
一句话：PR 是把“一个人的代码”变成“团队的代码”的仪式。
🚀 手把手教学：创建你的第一个 PR
前提条件
- 你已经在分支里做了些修改（比如我们在第3篇的 "feature-night-mode"）
- 并且已经 "git push" 到了 Gitee
步骤1：进入仓库，发起 PR
- 打开你的 Gitee 仓库页面
- 在上方导航栏找到 “Pull Requests”
- 点击 “新建 Pull Request” 按钮
你会看到一个比较页面：
+------------------------------------------------+ | 新建 Pull Request | +------------------------------------------------+ | 源分支: [你的用户名/my-knowledge-garden:feature-night-mode] ← 你的改动在这里 | 目标分支: [你的用户名/my-knowledge-garden:main] ← 要合到哪里去 | | | 比较结果： | | 可以自动合并 | | 1个提交，改变了1个文件 | +------------------------------------------------+
步骤2：填写 PR 信息
这是最关键的一步，决定了别人愿不愿意、能不能看懂你的代码。
标题：要像新闻标题一样清晰
❌ 差：“更新了一些东西”
✅ 好：“✨ 添加夜间模式切换按钮”
描述：用模板填充，清晰明了
🎯 做了什么
- 在
index.html中添加夜间模式切换按钮 - 点击按钮会将背景设为深色、文字设为白色
🔧 测试方法
- 打开首页
- 点击“🌙 夜间模式”按钮
- 观察页面是否变暗
📸 预览截图
（如果有UI改动，最好贴一张图）
✅ 关联 Issue
关闭 #5 （夜间模式需求）
关键词解释：
"关闭 #5"：当 PR 合并后，Issue #5 会自动被关闭（超方便！）
步骤3：提交 PR
点击 “创建 Pull Request”，你的作业就上交了！
👀 模拟审查：如果你有协作者
假设你的朋友来审查你的 PR，他会看到：
- 文件变动（Files changed）：逐行高亮显示你改了哪里
- 绿色 "+" 表示新增
- 红色 "-" 表示删除
- 发表评论：鼠标悬停在某一行，点“+”气泡就可以写评语
- “这个函数名可以更清楚一点”
- “这里少了个分号，会报错哦”
- 审批状态：
- ✅ 通过（Approve）
- 💬 评论（Comment）
- ❌ 驳回（Request changes）
这就是 Code Review（代码审查）——让代码变得更好的过程。
✅ 自己审查并合并
作为个人项目，你可能既是作者又是审查者，流程依然有价值：
- 检查改动：在“文件变动”里再看一遍自己写了什么
- 自我提问：
- 这些改动安全吗？
- 有没有不该上传的密码、密钥？
- 代码风格统一吗？
- 合并 PR：
- 点击 “合并 Pull Request”
- 选择合并方式（默认“Merge”即可）
- 填写合并提交信息
- 删除分支：合并后可以顺手删除远程分支（Gitee 会提示你）
合并后的效果：
"main" 分支现在有了夜间模式代码
"feature-night-mode" 分支的历史被融入主线
- Issue #5 自动关闭
- 所有记录永久可查
🧩 应用到“知识星球”：PR 工作流示例
典型的一次功能开发闭环
- Issue #7：✨ 添加收藏夹页面
- 创建分支 "feature-favorites" 并开发
- 完成开发 → 推送分支 → 创建 PR
- PR 标题：“✨ 实现收藏夹基础页面”
- PR 描述：“新增 favorites.html，含静态列表。关闭 #7”
- 自我审查或请朋友审查
- 合并 PR，删除 "feature-favorites" 分支
如果审查发现了问题？
- 直接在原分支上修改： "git add" → "git commit" → "git push"
- PR 会自动更新，无需新建
- 审查者再次查看，确认无误后合并
这就是迭代改进：提交 → 反馈 → 修正 → 通过。
⚠️ 常见问题与误区
Q1：PR 只能在两个人之间用吗？
完全不是。单人项目也用 PR：
- 强迫自己再读一遍代码
- 留下清晰的合并记录
- 熟悉标准协作流程，为以后团队合作打基础
Q2：PR 和 Merge 有什么区别？
- Merge（合并）：是 Git 的操作命令，单纯把代码合到一起
- Pull Request：是一整套流程和界面，包含审查、讨论、自动化等
Q3：PR 创建后发现目标分支错了？
可以修改：在 PR 页面侧边栏可以重新选择“目标分支”。
Q4：冲突（Conflict）怎么办？
如果 PR 无法自动合并，Gitee 会提示“存在冲突”，你需要：
在本地切换到该分支，拉取最新main并合并
git switch feature-xxx git fetch origin main git merge origin/main
手动解决冲突后
git add . git commit -m "解决合并冲突" git push
常见误区：
- 误区：PR 标题随便写后果：几个月后看历史，完全不知道这个 PR 是干嘛的
- 误区：一个 PR 包含五个不相关的功能后果：审查困难，回滚麻烦
- 误区：合并后从不删分支后果：仓库里堆满僵尸分支，越来越乱
📝 今日收获总结
✅ 理解 PR 的价值：代码的“质检站” + “讨论室”
✅ 学会创建 PR：选源分支、目标分支，写清晰描述
✅ 掌握 PR 描述模板：做了什么、怎么测、关联 Issue
✅ 体验审查视角：查看文件变动，理解 Code Review
✅ 完成合并闭环：合并 PR → 自动关 Issue → 删分支
你的工作流升级了：
想法 → Issue → 分支开发 → 推送 → PR审查 → 合并 → 删分支
这才是现代开发的规范节奏。
🔮 下篇预告 & 思考题
下篇预告：《Wiki：项目的“说明书”》
代码写好了，别人（或未来的你）怎么知道怎么用？下一篇学 Wiki——为你的知识星球写一份漂亮的说明书，让项目真正“可传承”。 你将学到：
- Wiki 是什么，为什么比 README 更强大
- 如何用 Markdown 编写项目文档
- 组织 Wiki 的最佳实践
今日思考题：
- 如果你要给朋友展示你的知识星球项目，你最希望在 PR 描述里写清楚哪三点？
- 为什么说“写好 PR 描述，是对未来自己的仁慈”？
动手小任务：
- 为你的知识星球做一个很小的改动（比如改一下标题文字）
- 走完整套流程：
- 切新分支 → 修改 → 提交 → 推送
- 在 Gitee 创建 PR，认真写标题和描述
- 审查自己的改动，然后合并并删除分支
- 观察合并后，对应的 Issue 是否自动关闭了。
📖 延伸资源
- Gitee PR 文档："gitee.com/help/articl…" (gitee.com/help/articl…)
- 如何写好 PR 描述：
- 动机：为什么要做这个改动？
- 做法：主要改了哪些地方？
- 测试：怎么验证它是对的？
- 代码审查清单（Checklist）：
- 代码能运行吗？
- 有注释吗？
- 有没有敏感信息泄露？
好的代码不只在于它能跑，还在于别人能看懂你为什么这么写。 PR 就是你讲述这段代码故事的地方。 下一节，我们给你的项目配上说明书，让它会说话 📚
