🐙 GitHub 使用教程（超详细・纯小白版）

1Git 和 GitHub 到底是什么？

先记住一句话：Git 是工具，GitHub 是网站。它俩不是一回事，但必须配合。

1.1 Git = 一个"时光机 + 存档器"

你写文档、写代码，经常会有"改着改着发现还是上一版好"的情况。Git 就是专门帮你记录每一次修改、随时回到任意历史版本的工具。它装在你自己电脑上，不需要联网也能用。
通俗比喻：

• 你每 commit（提交）一次，就像给当前文件夹拍了一张快照。
• 以后想回到某张快照，一条命令就能还原。

1.2 GitHub = 代码的"云端硬盘 + 朋友圈"

GitHub 是一个网站（github.com），它帮你把 Git 记录的项目存到网上，还能让别人看到、一起改、给你提建议。

• 备份：电脑坏了，代码还在 GitHub 上。
• 协作：多人同时改一个项目不打架。
• 展示：你的 GitHub 主页就是程序员的"作品集"，找工作很有用。

1.3 必须先懂的 8 个名词（小白必看）

2准备三件套：账号、Git、认证

2.1 注册 GitHub 账号

1. 打开 https://github.com ，点右上角 Sign up（注册）。
2. 填邮箱 → 设密码 → 取一个用户名（username）。
3. ⚠️ 用户名会显示在网址里（如 github.com/你的用户名），建议正式一点，以后找工作人家会看。
4. 验证邮箱（去收件箱点链接）。
5. 开启两步验证（2FA）：GitHub 现在强制所有账号开启 2FA，否则很多功能用不了。按网页提示用手机 App（如 Microsoft Authenticator / 1Password）扫码绑定即可。

2.2 安装 Git（装一次永久用）

• Windows：去 https://git-scm.com 下载 "Git for Windows"，一路 Next 安装。装完右键文件夹会出现 "Git Bash Here"，这就是 Git 命令行。
• Mac：终端输入 git --version，没装会提示你装"Command Line Tools"；或 brew install git。
• Linux（Ubuntu/Debian）：sudo apt install git

git --version

验证装好没：打开终端（Windows 用 Git Bash），输入
能显示版本号就成功了。

2.3 告诉 Git 你是谁（只需一次）

git config --global user.name  "你的用户名"
git config --global user.email "你的邮箱@example.com"

Git 每次提交都要记录"谁改的"。首次使用先配置用户名和邮箱（用你注册 GitHub 的邮箱）：

2.4 认证：小白最容易卡住的坑 ⚠️⚠️⚠️

remote: Support for password authentication was removed on August 13, 2021.

重点：从 2021 年 8 月起，GitHub 彻底禁用了"密码登录 Git"。 你 push 时如果输入账号密码，一定会失败，报类似：
正确做法二选一：

方案 A：用 Personal Access Token（PAT，推荐小白先用这个）

1. 登录 GitHub → 右上角头像 → Settings → 左侧 Developer settings → Personal access tokens → Tokens (classic)。
2. 点 Generate new token (classic)。
3. Note 写个名字（如 my-laptop），Expiration 选个时长（90 天或自定义）。
4. 勾选权限：至少勾 repo（控制仓库的全部权限）。
5. 点 Generate token，页面会显示一串 ghp_xxxx... 的字符。立刻复制保存！离开页面就再也看不到了。
6. 以后 git push 让你输密码时，密码那一栏粘贴这个 token（用户名还是你的 GitHub 用户名）。

方案 B：用 SSH 密钥（一劳永逸，推荐长期用）

# 1. 生成密钥（一路回车，不设密码也行）
ssh-keygen -t ed25519 -C "你的邮箱@example.com"

# 2. 把公钥内容复制出来
#    Windows:  cat ~/.ssh/id_ed25519.pub
#    Mac/Linux:  pbcopy < ~/.ssh/id_ed25519.pub  (或手动打开文件复制)

配置一次后，以后 push 再也不用输任何东西。
然后把复制的内容，粘贴到 GitHub → Settings → SSH and GPG keys → New SSH key → 保存。

3第一次建仓库（网页上点一点）

"仓库（Repository）"就是你的项目文件夹。第一次我们在网页上建：

1. 登录 GitHub，点右上角 + 图标 → 选 New repository（新建仓库）。
2. 填写：
3. Repository name（仓库名）：小写、用短横线连单词，如 my-first-project。
4. Description（描述）：一句话介绍，可空。
5. Public / Private：公开 / 私有。新手练手选 Public 还能攒贡献绿点。
6. 下面三个勾选项（建议新手全勾）：
7. ✅ Add a README file（自动生成一个说明文件）
8. ✅ Add .gitignore（选你用的语言模板，如 Python / Node，用来忽略垃圾文件）
9. ✅ Choose a license（选 MIT 等开源协议，个人练习可先不勾）
10. 点 Create repository（创建仓库）。

创建后你会看到一个文件列表页面，中间有个绿色的 < > Code 按钮——以后下载、复制地址都靠它。

4把仓库下载到电脑（Clone）

在电脑上编辑文件比在网页上好用一万倍。把仓库"克隆"到本地：

1. 在仓库页面点绿色 Code 按钮，复制 HTTPS 那一栏的地址（形如 https://github.com/你的用户名/my-first-project.git）。
2. 打开终端，进入你想放项目的文件夹（比如 cd Desktop），然后：

3. 会自动生成一个同名文件夹，进去：
```bash
cd my-first-project

git clone https://github.com/你的用户名/my-first-project.git

5最核心的三步曲：add → commit → push

记住这三个动作，你就掌握了 90% 的日常使用。
先理解三个"区"的比喻：

• 工作区：你正在改的文件（草稿纸）。
• 暂存区（Stage）：你挑出"这次要保存的改动"（放进购物车）。
• 版本库（Repository）：真正拍快照存档的地方（入库）。

流程就是：改文件 → add 挑出来 → commit 存档 → push 上传。

5.1 改点东西

用记事本或任意编辑器，打开仓库里的 README.md，随便加一行字，保存。

5.2 看当前状态

git status

会显示"哪些文件被改了（红色）"。

5.3 第一步：add（挑出来）

git add README.md        # 只挑这一个文件
# 或者把所有改动都挑出来：
git add .                # 注意最后有个点，代表"当前目录全部改动"

5.4 第二步：commit（存档 + 写说明）

git commit -m "更新了说明文档"

-m 后面跟的是这次改了什么的说明，一定要写清楚！以后回看历史就靠它。

5.5 第三步：push（上传到 GitHub）

git push origin main

• origin = 你的 GitHub 仓库（远程地址的别名，默认就叫 origin）。
• main = 要上传到的分支名（默认主分支）。

5.6 以后偷懒写法

git push        # 不用再写 origin main

第一次 push 加了 -u 绑定后，以后直接：

6查看自己改了什么

git log                 # 看提交历史（按 q 退出）
git log --oneline       # 简洁版一行一条
git diff                # 看"还没 add"的改动具体内容
git diff --staged       # 看"已 add 但还没 commit"的改动

7分支：平行宇宙

为什么需要分支？ 假设你主线上是个能跑的项目，你想试个新功能，又怕改崩了。分支让你在"副本"上随便折腾，成功了再合并回主线，失败了直接扔掉，主线毫发无损。

7.1 查看 / 创建 / 切换分支

git branch                  # 看当前有哪些分支（* 号在谁前面就是当前分支）
git switch -c 新功能名       # 创建并切换到新分支（如 git switch -c add-login）
# 旧版 Git 用：git checkout -b 新功能名
git switch main             # 切回主分支

7.2 在分支上正常工作

切到新分支后，照常改文件 → add → commit。这些改动只存在这个分支里，不影响 main。

8合并分支与解决冲突

git switch main          # 先回到主线
git merge 新功能名         # 把分支的改动合并进来

功能在分支上做完了，要把它合回主线：

8.1 冲突（Conflict）是什么？

<<<<<<< HEAD
这是 main 上的内容
=======
这是分支上的内容
>>>>>>> 新功能名

如果 main 和你的分支改了同一行代码，Git 不知道听谁的，就会报冲突。文件里会出现这样的标记：
解决步骤：

1. 用编辑器打开有冲突的文件，手动决定保留哪一段（把 <<<<<<<、=======、>>>>>>> 这些标记也删掉）。
2. 保存后：

> 冲突不可怕，它就是 Git 在问你"这行听谁的"，你选一个删掉标记就行。

---

## 九、Pull Request：团队协作的灵魂

**Pull Request（简称 PR）** = "我改好了，请审查并合并"。哪怕你一个人写项目，用 PR 也能留下清晰的修改记录。

完整流程：
1. 在**分支**上完成改动，并 `git push origin 分支名` 推到 GitHub。
2. 打开 GitHub 仓库页面，通常会弹出黄色提示：**"Your recently pushed branches" → Compare & pull request**，点它。
   - 或点顶部 **Pull requests** 标签 → **New pull request**。
3. 左边选 `base: main`（要合入的分支），右边选 `compare: 你的分支`。
4. 写标题和说明（改了啥、为什么），点 **Create pull request**。
5. 队友/你自己审查 → 点 **Merge pull request** → **Confirm merge**。
6. 合并后可点 **Delete branch** 删掉这个分支（保持仓库干净）。

> 比喻：PR 就像"提交作业 + 请老师批改"，改完没问题才"入库"。

---

## 十、参与开源：Fork 流程

想给别人的项目（比如一个知名开源库）做贡献，你没有直接修改权限，就要用 **Fork**：

1. 打开别人的仓库，点右上角 **Fork** → 会在**你自己的账号**下生成一份副本。
2. 把**你的副本** clone 到本地：
```bash
git clone https://github.com/你的用户名/那个项目.git

git add 冲突文件
git commit -m "解决冲突，合并分支"

1. 改代码、提交：

4. 去你自己的仓库页面，点 **Contribute** → **Open pull request**，向原仓库提 PR。
5. 原仓库作者审查通过后合并，你的名字就出现在贡献者列表里了！✨

### 10.1 保持你的 Fork 和原仓库同步
原仓库更新了，你的 Fork 不会自动跟着变。加一个"上游"远程：
```bash
git remote add upstream https://github.com/原作者/原项目.git
git fetch upstream
git merge upstream/main     # 把原仓库最新代码合进来

git switch -c fix-typo
# ...改文件...
git add .
git commit -m "修复了一个错别字"
git push origin fix-typo

9拉取别人的更新：pull

git pull origin main

别人改了 main，你想把最新代码弄到本地：
好习惯：每次开始干活前，先 git pull 一下，避免和别人的改动"撞车"产生冲突。

10.gitignore 和 README.md（项目门面）

12.1 .gitignore

# 例子：忽略所有 .log 文件和 node_modules 文件夹
*.log
node_modules/

有些文件不该进版本库：比如系统缓存、密码配置、编译产物。.gitignore 就是一张"黑名单"，写进去的文件 Git 会自动忽略。
建仓库时勾了模板就会自动生成，一般不用手改。

12.2 README.md

# 项目名称
一句话介绍这个项目是干嘛的。

## 功能
- 功能一
- 功能二

## 安装
\`\`\`bash
git clone 地址
cd 项目
\`\`\`

## 使用
写清楚怎么跑起来。

## 许可证
MIT

这是别人点进你仓库第一个看到的文件，等于项目门面。推荐结构：

11小白最常踩的 10 个坑（FAQ）

git remote set-url origin https://github.com/用户名/仓库.git

git restore 文件名          # 撤销"还没提交"的修改（Git 2.23+）
git checkout -- 文件名      # 旧版写法，效果同上
git log --oneline           # 找到想回到的版本号（前 7 位）
git checkout 版本号          # 回到那个历史快照

git commit --amend -m "新的说明"   # 改最近一次 commit 的说明

git config --global credential.helper store

Q1：push 时让我输密码，输了却失败？
→ 2021 年起不能用密码！密码那栏要填 Personal Access Token（见 2.4）。
Q2：报 Permission denied (publickey)？
→ 你用的是 SSH 地址，但没配 SSH 密钥。要么去配 SSH（2.4 方案 B），要么把远程地址换成 HTTPS：
Q3：冲突了怎么办？
→ 见第八章，手动改文件、删掉 <<< === >>> 标记、再 add + commit。
Q4：提交到错误的分支了？
→ 先 git switch 到正确的分支，再 git cherry-pick 提交号 把那次提交搬过去；或者简单点，在正确分支重做一遍。
Q5：误删了文件 / 改崩了，想回到上一版？
Q6：commit 的说明写错了能改吗？
Q7：main 和 master 到底用哪个？
→ 2020 年 10 月后 GitHub 新建仓库默认叫 main。老教程里写的 master 在新仓库上会报错"分支不存在"，换成 main 即可。
Q8：每次 push 都要输 token，太烦？
→ 配 SSH（2.4 方案 B）一劳永逸；或让 Git 记住凭证：
（下次输一次 token 后会缓存，注意别在公共电脑上用）
Q9：git status 显示很多不认识的文件？
→ 多半是没写 .gitignore，把 node_modules、__pycache__、.idea 等加进忽略列表。
Q10：网页上能直接改文件吗？
→ 能。点开任意文件 → 右上角铅笔图标 → 改完点 Commit changes，适合改错别字等小改动，不用开电脑。

12命令速查表（Cheat Sheet）

13GitHub 其他好用功能

• Issues：项目的"任务清单 + 留言板"，用来报 bug、提需求、讨论。
• Actions：自动化神器。每次 push 自动跑测试、自动部署，免费额度对个人够用。
• Pages：免费把仓库变成静态网站（适合放个人主页、文档）。你的 用户名.github.io 就是专属域名。
• Star / Watch / Fork：Star = 收藏；Watch = 关注更新；Fork = 复制一份。
• Discussions：比 Issues 更随意的社区讨论区。
• Codespaces：浏览器里直接开一个云端开发环境，不用在自己电脑装环境。
• 找好项目练手：在大型仓库搜标签 good first issue 或 help wanted，专给新手准备的入门任务。

14学习路线建议

1. 个人项目起步：建一个仓库，把自己平时写的小脚本、笔记传上去，练熟 add/commit/push。
2. 用分支：每个新功能开一个分支，做完合并，体验"平行宇宙"。
3. 参与开源：从 good first issue 开始，走一遍 Fork → 改 → PR 流程，攒贡献绿点。
4. 做作品集：把 3~5 个拿得出手的项目整理好 README，GitHub 主页就是你的简历。