GitHub 这名字，但凡写过代码的人应该都不陌生。但"用过"和"会用"之间，隔着的往往不是语法，而是一整套工作流的理解。我带过不少新人，也见过很多入行两三年的同事，GitHub 用得还是"上传下载"那一套——代码传上去就当备份，分支除了 main 基本不碰，遇到冲突就慌，更别提 Pull Request 这些协作功能了。这篇东西，我就按自己实际带人、带项目时总结出来的路子，把 GitHub 从概念到日常操作到协作流程，完整捋一遍。不是官方文档的翻译，是我自己用下来的经验和教训，适合刚接触 GitHub 的新手，也适合那些"用了一阵子但总觉得哪里不对劲"的开发者。
1. 别把 GitHub 当成网盘：先理解版本控制在解决什么问题
1.1 一个事故案例：覆盖代码的代价
先说个我印象特别深的事故。几年前团队里有个同事，负责一个模块的改动，他习惯的做法是：本地改完代码，直接复制整个文件夹，用网盘传一份"备份"，然后再继续改。听起来挺稳妥对吧？结果有一次，他把一个旧版本的文件夹直接拖进了项目目录，系统弹出"是否替换"，他点了确认，一整天的改动全部被覆盖。最崩溃的是，那个"备份"其实是他三天前传的版本。
这不是个例。我见过太多人第一次接触 GitHub 时，脑子里还是网盘的逻辑：把代码放上去，图个"云端存储"和"换电脑能拉下来"。但 GitHub 核心解决的问题，根本不是存储，而是版本管理——它记录的是每一次变更，而不是一个最终快照。
1.2 Git 的三个核心动作：提交、分支、合并
Git 的底层概念很多，但日常工作中真正反复用到的就三个：提交（commit）、分支（branch）、合并（merge）。
提交是给代码拍一张"底片"。每次提交都会记录：改了哪些文件、改了什么内容、谁改的、什么时间改的、提交信息是什么。Git 之所以强大，是因为这些底片不是简单的覆盖关系，而是像一棵树的分叉——你随时可以回到任意一张底片，也可以从某个底片再拉出一条新路线。
分支就是从某张底片上分出去的另一条路线。比如你在开发新功能，担心把主程序改坏，就拉一个分支出来，在分支上随便折腾，改坏了删掉重来都不影响主路线。
合并则是把两条路线的改动汇合到一起。这部分容易出问题——两条路线都改了同一个文件的同一行，Git 不知道该听谁的，就会产生我们常说的"冲突"。
理解这三个动作，再回头看 GitHub 就清楚多了。
1.3 GitHub 在整个流程里扮演的角色
Git 是装在你电脑上的版本管理工具，它自己就能记录历史和分支，不需要联网。那 GitHub 加了什么？三样东西：远程仓库、协作机制、可视化界面。
远程仓库让你和别人的 Git 仓库能够同步——你用 Git 在本地提交，然后 push 到 GitHub 上，同事从 GitHub 上 pull 下来，大家基于同一套历史往前推进。协作机制就是 Pull Request、Issue、Code Review 这一整套，让"你改完代码告诉我一声，我看过没问题再合进去"这个流程变得规范和可追溯。可视化界面则让你能在网页上直接看代码、看改动记录、看每个人的贡献，比在命令行里敲git log直观得多。
所以对你来说，Git 是工具，GitHub 是平台。命令是在本地敲的，协作是在平台上完成的。搞懂这个分工，后面每一步都有方向感。
2. 环境准备与第一次连接：从注册到成功推送代码
2.1 注册、建仓库和第一次 clone
注册账号没什么好说的，选一个看起来专业的用户名，因为别人会通过 GitHub 认识你。建仓库时有个容易忽略的点：要不要勾选"Add a README file"。
README 是仓库的说明书，我会建议勾上，但很多人不理解它到底有什么用。实际上，README 不只是给别人看的，也是给三个月后的自己看的。你写清楚这个项目解决什么问题、怎么跑起来、目录结构是什么样，下次自己回来接手都省很多事。
建好仓库后，页面会提示你要不要 clone 到本地。这里的关键理解是：clone是把你 GitHub 上的仓库整个复制到本地，并且自带远程仓库地址的关联信息。也就是说，执行完git clone <仓库地址>之后，你不需要再手动设置"这是从哪来的"，Git 已经记住了。
至于"把本地已有项目传到 GitHub"——新建的仓库页面会给你一组命令，比如git remote add origin、git push -u origin main，这属于把本地仓库和远程仓库关联起来的过程，我们放到后面演示流程里一起走。
2.2 SSH Key 配置：为什么我强烈建议用它而不是密码
推送代码时，GitHub 需要确认"是你本人"。方式有两种：HTTPS 加用户名密码（或者 Token），以及 SSH Key。
我几乎都会让新人配置 SSH Key，理由很简单：配一次，之后永久免密，而且比密码安全得多。原理是，你在本地生成一对密钥——一个私钥一个公钥，私钥留在你电脑上，公钥放到 GitHub 账号里。推送代码时，GitHub 用公钥验证你的身份，而签名用的私钥从不离开你的电脑。
操作步骤如下：
# 生成密钥对，一路回车即可 ssh-keygen -t ed25519 -C "你的邮箱" # 查看公钥内容 cat ~/.ssh/id_ed25519.pub把输出的内容复制，到 GitHub 的 Settings -> SSH and GPG keys -> New SSH key 页面粘贴保存。
之后，你在 clone 仓库时选 SSH 地址（形如git@github.com:用户名/仓库名.git），就能直接推送，不用再输密码。如果之前已经用 HTTPS 方式 clone 过，可以改一下远程地址：
git remote set-url origin git@github.com:用户名/仓库名.git2.3 第一次 push 的完整命令链
假设本地已经有一个项目文件夹，还没有 Git 初始化过。完整走一遍：
# 进入项目目录 cd my-project # 初始化本地仓库 git init # 把当前目录所有文件加入暂存区 git add . # 提交到本地仓库，-m 后面写提交说明 git commit -m "初始提交" # 关联远程仓库，地址换成你自己的 git remote add origin git@github.com:用户名/my-project.git # 推送，-u 的意思是建立本地分支与远程分支的关联 git push -u origin main这里有几个细节值得说。第一个是git add .和git commit是两步动作——add是把文件放入"暂存区"，commit才是把这些文件正式记录进历史。这个概念新手很难第一次就理解，你可以这样想：add 是挑选要拍照的文件，commit 是按下快门。
第二个是提交信息-m "初始提交"。我见过有人永远写"update"、"修改"，这是坏习惯。提交信息是给未来的自己和同事看的，写清楚"做了什么"和"为什么做"，比写一堆代码注释还重要。后面排查问题，基本全靠提交信息认路。
第三个是.gitignore文件。如果项目里有临时文件、日志、依赖包这些不需要进版本库的东西，你迟早需要它。GitHub 新建仓库时可以选模板，也可以自己写几行：
# 忽略日志文件 *.log # 忽略临时文件 .tmp/不然你会发现，把node_modules或者target这种目录 push 上去，仓库越来越大，同事 clone 下来还容易出问题。
提示：第一次 push 前，先确认你 GitHub 仓库默认分支名是 main 还是 master。老项目可能是 master，新项目默认 main。分支名不一致时，push 会报错，用
git branch -M main可以重命名当前分支。
3. 日常协作的完整闭环：分支、Pull Request 与 Code Review
3.1 分支策略：为什么不要直接在 main 上开发
很多新手习惯直接在 main 分支上改代码，改完一 push，完事。单干的时候问题不大，但一旦有两个人同时在这个仓库里干活，马上就会出事。
举个例子：你在 main 上改了登录模块，同事在 main 上改了支付模块，你们各自 commit 后，先后 push。GitHub 收到第二个 push 时发现，远程的 main 比你本地多了几个提交，就会拒绝推送——你必须先git pull把同事的改动拉到本地合并，再重新 push。如果两个人的改动正好碰了同一段代码，那就是"合并冲突"现场。
所以规范流程里，main 分支应当始终处于"随时能上线"的状态，日常开发应该放在其他分支进行。这就是"分支策略"要解决的问题。
常见的策略有两种。小团队用"GitHub Flow"就够了：main 保持稳定，新功能拉一个分支，开发完成后发起 Pull Request，审查通过后合并回 main。
# 拉一个新分支，-b 表示创建并切换 git checkout -b feature/login # 开发完提交、推送 git add . git commit -m "实现登录功能" git push origin feature/login大一点的项目会用"Git Flow"，多出 develop、release、hotfix 这些分支，流程更长更严谨，但小团队用不上，反而增加负担。我的建议是：先按 GitHub Flow 来，等团队规模大了，觉得流程不够用了，再上 Git Flow。分支策略没有绝对正确，只有适不适合。
3.2 发起 Pull Request 的正确姿势
分支推上去之后，在 GitHub 仓库页面会出现一个醒目的"Compare & pull request"按钮，点进去就是发起 Pull Request（简称 PR）的界面。
PR 是干什么的？一句话：请求项目的维护者，把你分支上的改动合并到 main 分支，并且在此之前，请他们审查这些改动。它不是简单"发个通知"，而是把代码审查（Code Review）这件事，变成了工作流里固定的一环。
写 PR 描述的时候，我建议套一个简单模板：
## 本次改动 - 实现了登录接口，支持手机号和验证码登录 - 增加了登录状态校验中间件 ## 测试情况 - 本地跑通登录流程，验证码正确/错误场景均覆盖 - 与后端联调通过 ## 备注 - 依赖 settings 模块新增的 JWT 密钥配置，需要在部署时补充写清"改了什么"和"怎么验证的"，审查者就不用翻着代码猜你的意图，效率高很多。我自己看 PR 时最烦的就是描述只有一句话"fix bug"，点进去看半天不知道改了哪里，更不知道有没有副作用。
3.3 Code Review 阶段，GitHub 能帮你做什么
PR 发出去后，代码审查者会在 GitHub 的 PR 页面上看到：改了哪些文件、每个文件里改了哪些行、旧代码和新代码的对比。这些都不需要审查者自己在本地拉分支看，网页上就能完成大部分工作。
审查者可以针对具体某一行代码发表评论，可以提出修改意见，可以 approve 表示通过，也可以 request changes 表示需要修改。这个过程看起来只是点几个按钮，但它带来的价值是巨大的：每一行进入 main 分支的代码，至少经过了一个人的目光检查。很多 bug、安全隐患、风格问题，就是在这种检查中被拦下来的。
我自己的经验是，初学者看别人代码的 PR 时，能学到的东西往往比写自己的代码还要多。你会看到别人怎么组织函数、怎么命名变量、怎么设计模块边界——这些是文档里学不来的。
给开发者的一个提醒：PR 审查被驳回不是丢脸的事。我一开始也觉得很受打击，后来发现，审查者的每一句意见，其实都是在帮你避免线上事故。心态摆正，Code Review 就是团队里最好的一对一技术课。
4. 新手最容易踩的坑：冲突、误提交与撤回操作
4.1 合并冲突是怎么产生的，怎么解决
合并冲突是 Git 使用者最头疼的问题，但说实话，冲突本身并不可怕——可怕的是不理解冲突是怎么来的，然后乱敲命令越搞越乱。
冲突的产生条件很简单：两条分支在同一个位置做了不同的修改。Git 在合并时发现，这一行代码在分支 A 上是"甲"，在分支 B 上是"乙"，它没法替你做决定。
假设你在feature/login分支上修改了login.py的第 10 行，同事在main分支上把同一个文件的第 10 行改成了其他内容。你执行合并操作时，Git 会把文件里冲突的部分标记出来：
<<<<<<< feature/login def login(username, password): ======= def login(email, token): >>>>>>> main<<<<<<<到=======之间是你分支上的内容，=======到>>>>>>>之间是 main 分支上的内容。你需要自己判断：到底需要哪一边，或者两边各取一部分，然后手动修改文件，把标记符号全部删掉，再提交。
这个过程我称之为"Git 把皮球踢给了你"——它不能判断业务逻辑上的对错，只能帮你把矛盾的地方呈现出来。所以解决冲突不是技术问题，而是业务问题：你要理解上下文才能做决定。
减少冲突的办法也是有的。第一，尽量让分支的生命周期短一些，别一个分支写一个月才合并，积攒的冲突会越来越多。第二，频繁把 main 的更新合并到你的特性分支上，让冲突一点一点地消化，比最后一次性面对几十处冲突轻松得多。
4.2 误提交之后如何撤回
Git 最贴心的设计之一是：它默认你"做了很多蠢事"，所以给了你后悔药。常见的两种场景：
场景一：commit 写错了，还没推送到远程。想修改提交信息，或者想把这次提交追加更多改动：
# 修改最近一次提交的信息 git commit --amend这个命令会打开编辑器让你修改提交说明。注意，它实际上是"创建了一个新提交替换原来的那个"——如果你已经把提交推送到远程了，并且有别人已经拉取了这个分支，那么amend之后历史就分叉了，会带来麻烦。所以amend只适合处理还没推送的提交。
场景二：想撤销某次提交，回到它之前的状态。又分两种需求：
# 保留修改，只撤销提交动作（文件回到暂存区） git reset --soft HEAD~1 # 不保留修改，彻底回到上一个提交的状态 git reset --hard HEAD~1HEAD~1表示"前一个提交"。--hard是很危险的操作，它会把工作区的修改全部丢弃，而且这些修改不会出现在任何历史里。我每次执行git reset --hard之前，都会强迫自己先确认一遍：这些改动是不是真的不重要了？
一个更稳妥的做法是，先把当前状态备份成一个分支：
git branch backup/wo-de-cuo-wu git reset --hard HEAD~1万一后悔了，还能git checkout backup/wo-de-cuo-wu回来。
4.3 网络异常与推送失败：不要乱试命令
新手在 push 失败时最容易慌，一慌就开始百度，然后复制一堆看不懂的命令往终端里一个接一个地敲。我见过最惨的案例是一个人把git push -f当成"强制推送"用，结果把同事的提交给覆盖了。
push 失败的常见原因就那么几个：
第一，远程分支有新的提交，你的本地落后了。解决方式是按提示执行git pull，把远程的改动拉到本地合并，再 push。
第二，网络原因连接不上 GitHub，报错信息通常是connection timed out或者Failed to connect to github.com port 443。这种时候不要反复尝试，也不要尝试任何修改历史的命令——问题不在你的 Git 操作上，是网络链路的问题。检查一下代理设置、换一个更稳定的网络环境、过一段时间再试，都比乱敲命令安全。
第三，权限问题，报错是permission denied。检查你的 SSH Key 是否已经在 GitHub 账号里、是否用对了远程地址（SSH 地址而非 HTTPS 地址）。
这里我特别强调：任何带-f（force）的参数，在你不确定后果之前都不要用。git push -f会强制覆盖远程分支的历史，在协作项目中，这等同于"删除别人的工作"。真需要用到强制推送的场景是极少数的，而且应该先和团队沟通确认。
5. 从零到一：一个完整任务的演示流程
5.1 一个场景，串起全部知识点
前面讲了很多概念和零散的命令，到这里我们完整走一遍。假设这样一个场景：你是团队新人，需要在项目里加一个"用户积分排行榜"功能，流程从建分支开始，到 PR 被合并结束。
项目主分支叫main，你本地已经 clone 过了。
# 1. 先同步 main 到最新 git checkout main git pull # 2. 拉一个功能分支，命名要能看出功能 git checkout -b feature/leaderboard # 3. 开始写代码... 写完几个文件后，看看状态 git status # 4. 把改动加入暂存区，再提交 git add . git commit -m "实现排行榜查询接口" # 5. 再看看有没有遗漏的改动 git status # 6. 推送到远程 git push origin feature/leaderboard5.2 从 push 到 PR 再到合并
push 成功后，GitHub 上会出现一个提示条，点击"Compare & pull request"，进入 PR 创建页。
我填 PR 描述时会按前面说的模板来，标题写成"feat: 用户积分排行榜查询接口"，让人一眼就知道这是新功能还是修 bug，改了哪块。
提交 PR 之后，项目维护者会收到通知。他会在 PR 页面里逐行查看改动，可能会提出意见，比如"这个 SQL 查询缺少索引，数据量大时会慢，建议加上"。你需要修改代码，再 commit 到原来的分支上——注意，你不需要重新发起一个新的 PR，只要持续往feature/leaderboard分支推送新的提交，PR 页面会自动更新。
审查通过后，维护者会点击"Merge pull request"。合并完成后，feature/leaderboard分支上的所有提交就进入了main分支。
5.3 流程里的常见问题和我的习惯
这个流程走下来，有几点我每次都会这么做，算是经验之谈。
第一，每次开始新任务，先git checkout main && git pull。确保你的起点是最新的。很多人冲突的根源不是操作问题，而是从一个陈旧的 main 出发开始开发。
第二，尽量保证每个 PR 是"小而完整"的。一次改动几十个文件的巨型 PR，审查者很难认真看完，容易漏掉问题；但只改一个标点的碎片 PR，又会显得没必要。我一般以一个完整的功能点为边界，改动控制在几个文件以内。
第三，提交信息里加上关联 Issue 编号。GitHub 支持在提交信息里写fixes #123，这样可以自动关闭对应的 Issue，同时让代码和问题描述关联起来。以后翻历史时，看到一个 commit，点进去就能知道当初是哪个问题引起的，排查效率高很多。
第四，开发过程中如果发现 main 分支更新了，及时合并过来。
# 在功能分支上 git fetch origin main git merge origin/main这会让你的功能分支始终基于最新代码，避免最后合并时爆出大量冲突。
6. 关于 GitHub 的其他高频功能：Issue、Actions 和 README
6.1 Issue：不只是提 bug 用的
Issue 是 GitHub 内置的"问题系统"。很多人把它当作 bug 反馈通道，这没有错，但它的用途远不止于此：新功能建议、任务拆分、讨论备忘，都可以创建 Issue 来跟踪。
我在开源项目里看到习惯比较好的用法，是把一个大功能拆成若干个小 Issue，每个 Issue 对应一个可独立完成的单元，然后在 PR 描述里用fixes #编号关联。这种做法的好处是，整个项目的进展可以通过 Issue 列表一览无余——有哪些任务在做、哪些完成了、哪些还没开始。
对于个人项目，同样值得用。你有一个想法，先开一个 Issue 记录下来，命名"实现积分排行榜"，内容包括需求描述、涉及文件、验收标准。这样即使一时没时间做，想法也不会丢；等开始做时，顺着 Issue 就能快速进入状态。
6.2 GitHub Actions：把自动化跑起来
GitHub Actions 是 GitHub 内置的 CI/CD 工具，简单理解就是：你在 GitHub 上定义一个工作流，每当指定事件发生时（比如 push、PR 创建），GitHub 就自动在一个虚拟机器上执行你定义好的脚本。
最常见的用途是：每次 push 后自动运行测试，确保代码质量。配置写在仓库的.github/workflows/目录下，用 YAML 格式：
name: CI on: push: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: 设置 Python uses: actions/setup-python@v5 with: python-version: '3.12' - name: 运行测试 run: pytest这个文件的意思是：当 main 分支有 push 时，在最新的 Ubuntu 环境上，拉取代码、安装 Python 3.12、执行pytest。如果测试失败，PR 上会出现红色叉号，维护者就知道这次改动有问题。
对个人项目，Actions 的价值主要体现在自动化部署和自动化测试。我自己的博客就是通过 GitHub Actions 在每次 push 后自动构建并部署的——写好文章推上去，几秒后网站就更新了，整个流程不需要本地跑任何构建命令。
6.3 一个内容详实的 README，价值被低估了
最后再聊聊 README。GitHub 仓库的首页默认展示 README 的内容，它是访客对项目的第一印象，也是使用文档。
我刚开源项目时，README 只有一句话"这是我的项目"，后来有用户给我提 Issue 问"怎么安装？怎么用？"，我才意识到 README 的价值。一个好的 README 至少应该包含：
# 项目名称 一句话介绍：这个项目解决什么问题。 ## 安装 pip install xxx ## 快速开始 给出最小可运行示例 ## 文档 指向更详细的文档链接 ## 贡献 如何参与开发、如何提交 PR ## License 开源许可证写 README 有个技巧：把你想象成一个完全不了解项目的用户，从零开始按照 README 操作，看能不能顺畅地跑起来。如果你自己照着文档都装不起来，那说明文档写得还不够清楚。
根据我个人的经验，把 GitHub 从"上传下载工具"升级为"协作工作流"，最关键的一步不是熟悉更多命令，而是建立起"每次修改都可追溯"的习惯——所有代码都走分支、所有合并都走 PR、所有提交信息都写得让人看得懂。这套习惯一旦形成，代码质量、协作效率、问题排查速度都会有一个明显的提升。另一个小建议：没事多去逛一逛开源项目，看看别人发的 PR 是怎么写的、维护者是怎么 review 的、Issue 里是怎么沟通的——这些东西比你专门去啃官方文档节省时间，而且在实战里马上用得上。