github协作功能Pull Request（PR）指南

Pull Request 简介

拉取请求（Pull Request）是将代码修改合并到项目中的提议。它是 GitHub 的核心协作功能，支持在合并前对修改进行讨论与审核，有助于团队协作、尽早发现问题并保证代码质量。在开源项目中，Pull Request 被广泛用于参与社区贡献。

对于 GitHub 上其他人建立的项目，我们想要对其进行完善和修改，并向项目的维护者提出合并请求时，就需要使用 Pull Request 功能。整个流程是这样的：Fork 仓库 → 建分支 → 改代码 → 推到 Fork 仓库 → 向原项目提 PR → 原项目维护者审核后合并。

下面我们给出使用Pull Request协作开发时的用到每一步命令，并解释每个命令的作用

Pull Request 协作流程

1. 克隆你的 Fork 到本地

git clone git@github.com:你的用户名/项目名.git
cd 项目名

• git clone <仓库地址>：将远程仓库完整地复制到本地。这里用的是 SSH 地址（以 git@github.com: 开头），如果你配置了 SSH 密钥，就可以免密操作。你也可以使用 HTTPS 地址，但每次推送可能需要输入账号密码。
• cd 项目名：进入项目目录，后续操作都在这个目录下进行。

克隆完成后，本地仓库会自动关联一个名为 origin 的远程仓库，指向你的 Fork。

2. 添加上游（原项目）远程（同步用）

git remote add upstream git@github.com:原作者/项目名.git
# 验证
git remote -v

• git remote add upstream <地址>：给当前本地仓库添加一个新的远程仓库，习惯上命名为 upstream（上游），指向原作者的仓库。这样你就可以随时从原项目拉取最新的更新，保持本地代码与上游同步。
• git remote -v：列出所有已配置的远程仓库及其地址，用来验证 upstream 是否添加成功。你会看到类似这样的输出：origin git@github.com:你的用户名/项目名.git (fetch)
  origin git@github.com:你的用户名/项目名.git (push)
  upstream git@github.com:原作者/项目名.git (fetch)
  upstream git@github.com:原作者/项目名.git (push)

为什么需要 upstream？ 因为你的 Fork 是从原项目复制过来的，但原项目后续可能会有新的提交，如果不及时同步，你的代码就会落后，提 PR 时容易产生冲突。

3. 基于最新代码建新分支（别在 main 直接改）

# 拉取上游最新代码
git fetch upstream
git checkout main
git merge upstream/main
# 创建功能分支
git checkout -b feature/你的功能名

• git fetch upstream：从 upstream 远程仓库获取最新的提交和历史，但不会自动合并到你的当前分支。这让你可以先看看有哪些更新，再决定如何合并。
• git checkout main：切换到本地 main 分支（也可能是 master，视项目而定）。
• git merge upstream/main：将 upstream/main 分支上的最新提交合并到当前所在的本地 main 分支。这一步让本地 main 与上游保持同步。
• git checkout -b feature/你的功能名：基于当前分支（已经是最新的 main）创建一个新的分支，并立即切换过去。-b 的意思是创建并切换。这个新分支将用于你的修改，命名建议见下文。

为什么不在 main 上直接改？ 直接在 main 上修改会使你的主分支与上游产生差异，后续如果需要同步上游更新会变得混乱。创建独立的功能分支，可以让你同时开发多个功能，也便于维护者审查——他们只看到这个分支上的改动，清晰明了。

4. 修改、提交、推到你的 Fork

git add .
git commit -m "feat: 描述你的修改"
git push origin feature/你的功能名

• git add .：将当前目录下所有已修改、新增的文件添加到 Git 的暂存区（staging area）。你也可以指定具体文件，比如 git add src/index.js。. 是通配符，表示当前目录及子目录的所有改动。
• git commit -m "提交信息"：将暂存区的改动打包成一个新的提交，并附上简短的描述。提交信息的格式建议遵循社区规范（例如 Conventional Commits），后面会介绍。
• git push origin feature/你的功能名：将本地分支 feature/你的功能名 推送到远程仓库 origin（也就是你的 Fork）上。这样 GitHub 上就有了你新分支的代码，为下一步提 PR 做好准备。

5. 网页端提交 PR

至此，你的 PR 就成功提交到了原项目，等待维护者审核。

6. 后续

提交 PR 以后，由原项目维护者审核、评论、合并。在此期间你可能会收到反馈，需要根据建议修改代码。以下是常见的后续操作：

• 如果维护者要求修改：你可以在本地同一个分支上继续修改，然后再次 git add、git commit、git push origin 你的分支名。推送后 PR 会自动更新，无需重新创建。
• 如果出现冲突：当你的 PR 与目标分支（例如 main）的最新代码有冲突时，GitHub 会提示“This branch has conflicts that must be resolved”。你需要先在本地解决冲突：git checkout main
  git pull upstream main # 拉取上游最新代码
  git checkout feature/你的功能名
  git merge main # 将 main 合并到功能分支，解决冲突
  git push origin feature/你的功能名
  推送后 PR 中的冲突状态会自动更新。注意：不要在 GitHub 网页上直接解决复杂冲突，最好在本地测试后再推送。
• 如果 PR 被合并：恭喜你，你的贡献已成功加入原项目！之后可以同步你的 Fork 以保持最新：git checkout main
  git pull upstream main
  git push origin main # 更新你的 GitHub 上的 main 分支
  然后可以删除本地和远程的功能分支（可选）：git branch -d feature/你的功能名
  git push origin –delete feature/你的功能名

分支命名方式

在创建分支时，推荐使用下面的分支命名格式：

类型/简短描述

或

类型-简短描述

这种命名方式能让你（和项目维护者）一眼看出分支的用途，也方便后期自动化脚本识别。

1. 类型

• fix/：修复 bug
• feat/：新增功能
• refactor/：重构代码（不改变功能）
• docs/：文档修改
• style/：格式、空格、分号等（不影响代码运行）
• test/：测试相关

2. 描述

• 小写英文
• 单词之间用 – 连接
• 简洁说明做了什么

例如：

feat/add-user-login-and-fix-api-error # 添加用户登录并修复 API 错误
fix/login-bug-and-add-refresh-token # 修复登录 bug 并添加刷新令牌
docs/update-readme-usage # 更新 README 使用说明

团队协作时，分支一多就容易混乱。清晰的命名可以帮助你快速切换，也让 CI/CD 工具能够根据分支类型自动执行不同的测试或部署任务。比如，只有 feat/ 分支才会触发构建预览环境。