GitHub：远程仓库与协作流程

这一课你将能做到

1. 把本地仓库推送到 GitHub，完成 push/pull/clone 的完整远程操作
2. 发起和审查 Pull Request，用分支协作避免直接在 main 上开发
3. 用 GitHub Pages 部署静态页面，让项目直接可访问

为什么要学

Git 管本地版本，GitHub 管远程协作。你的代码不能只存在自己电脑上——硬盘会坏、电脑会丢、你需要在不同设备上工作，更重要的是团队协作必须有一个「中央仓库」作为信源。

GitHub 不只是代码托管，它是现代软件开发的基础设施：Issue 跟踪 bug、Pull Request 做代码审查、Actions 做自动化测试和部署、Pages 做免费静态托管。不会 GitHub，你就无法参与真实的团队开发。

先建立图像

本地仓库（你的电脑）
    ↑↓ git push / git pull
远程仓库（GitHub）
    ↑↓ fork / PR
上游仓库（团队主仓库）

个人开发时，本地和远程是一对一同步。团队协作时，每个人 fork 或 clone 中央仓库，通过 Pull Request 把代码合回去。

跟着做

步骤 1：创建远程仓库

1. 登录 github.com，点击右上角 + → New repository
2. 填写仓库名（如 my-first-repo），选择 Public（开源）或 Private（私有）
3. 不要勾选 "Initialize this repository with a README"（我们本地已有仓库）
4. 创建后看到提示页面，复制 HTTPS 地址（如 https://github.com/用户名/my-first-repo.git）

步骤 2：本地仓库关联远程并推送

# 进入本地已有的 Git 仓库
cd my-project

# 关联远程仓库（origin 是默认别名）
git remote add origin https://github.com/用户名/my-first-repo.git

# 把本地 main 分支推送到远程（-u 建立追踪关系）
git push -u origin main

# 输入 GitHub 用户名和个人访问令牌（Token）
# 注意：GitHub 已废弃密码登录，必须用 Token

获取 Token：GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token，勾选 repo 权限。

步骤 3：日常推拉流程

# 开始工作前先拉取最新代码
git pull origin main

# 开发、提交（和本地流程一样）
git add .
git commit -m "添加新功能"

# 推送到远程
git push origin main

如果远程有更新你本地没有，push 会被拒绝。先 git pull 合并远程更改，再 push。

步骤 4：克隆已有仓库

如果你想在另一台电脑或新目录开始工作：

# 克隆到本地
git clone https://github.com/用户名/my-first-repo.git

# 进入项目
cd my-first-repo

# 查看远程地址
git remote -v

clone 会自动创建文件夹、初始化 Git、关联远程、下载所有历史。

步骤 5：Pull Request 协作流程

Pull Request（PR）是团队协作的核心机制：不在 main 上直接提交，所有改动通过 PR 审查后再合并。

# 1. 创建功能分支
git switch -c feature-navbar

# 2. 开发并提交
git add .
git commit -m "Add responsive navbar"

# 3. 推送分支到远程
git push -u origin feature-navbar

# 4. 在 GitHub 网页上点击 "Compare & pull request"
# 5. 填写 PR 标题和描述，请求审查
# 6. 审查者评论、要求修改
# 7. 修改后再次 push，PR 自动更新
# 8. 审查通过，点击 "Merge pull request"
# 9. 删除远程分支，本地执行 git switch main && git pull

PR 的好处：

• 每个改动都有审查记录，出了问题可追溯
• CI 可以自动跑测试，没过不能合并
• 代码讨论围绕具体代码行展开，效率高

步骤 6：Fork 与贡献开源

如果你想给别人的项目提代码（比如给 React/Vue 修 bug）：

1. 在目标仓库页面点击右上角 Fork，复制一个仓库到你名下
2. git clone 你 fork 的仓库到本地
3. 创建分支、修改、提交、push 到你的 fork
4. 在 GitHub 上发起 Pull Request（从 fork 的分支到原仓库的 main）
5. 原仓库维护者审查后决定是否合并

步骤 7：GitHub Pages 部署

GitHub Pages 可以免费托管静态网站，适合个人博客、项目演示页。

1. 进入仓库 → Settings → Pages
2. Source 选择 "Deploy from a branch"
3. Branch 选择 main，文件夹选 / (root)，保存
4. 等待几分钟，访问 https://用户名.github.io/仓库名/

如果要自定义域名：Pages 设置里填域名，同时在仓库根目录放 CNAME 文件（内容就是域名）。

讲清楚要点

1. 远程仓库是本地仓库的镜像：push 把本地提交送上去，pull 把远程提交拉下来，clone 是完整复制。三个命令覆盖 90% 的日常操作。
2. 分支是隔离单位：个人项目可以直接 push main；团队协作必须在功能分支上开发，通过 PR 合并。这是行业铁律。
3. Token 是新的密码：GitHub 已全面禁用账号密码进行 Git 操作，必须用 Personal Access Token。把 Token 当成密码保管，不要泄露。
4. PR 是沟通工具，不只是代码合并：好的 PR 描述要说清「改了什么、为什么改、怎么测试」。审查者通过 PR 理解改动意图，不是只挑代码风格。
5. GitHub Pages 只支持静态内容：纯 HTML/CSS/JS 可以直接部署；需要后端（Node/Java）的项目不能直接用 Pages，后面会学 Vercel/Netlify。

你可能会懵的地方

• origin 是什么？ 是远程仓库的默认别名。你可以把它理解成「远程仓库的快捷方式」。git remote -v 能看到 origin 指向的具体 URL。

• HTTPS 和 SSH 有什么区别？ HTTPS 每次操作都要输用户名和 Token；SSH 配置一次密钥对，之后免密操作。个人电脑推荐用 SSH，配置方法：生成密钥对 → 把公钥贴到 GitHub Settings → SSH keys。

• push 被拒绝怎么办？ 通常是远程有你本地没有的提交。先 git pull origin main，处理可能的冲突，然后再 git push。

• PR 和 branch 的关系？ PR 是 GitHub 网页上的「请求合并」操作，branch 是 Git 里的代码分支。发起 PR 时，GitHub 会比较两个 branch 的差异，允许审查和讨论。

• 为什么我的 Pages 没生效？ 检查：仓库是 Public 或 Pro 账号的 Private；部署分支和目录设置正确；index.html 在根目录；等待 2-5 分钟。F12 的 Network 面板看是否有 404。

错法对照

错法	问题	正解
用 GitHub 密码做 git 认证	403 报错，认证失败	用 Personal Access Token
直接在 main 分支上开发	无法做代码审查，容易破坏主线	功能分支 + PR
PR 描述只写「更新」	审查者看不懂改动意图	写清楚改了什么、为什么、怎么测
push 前从不 pull	频繁冲突，历史分叉	每天开始工作先 pull
fork 后直接改 main	后续同步上游困难	fork 后切分支改，保持 main 干净
把 node_modules 推上 GitHub	仓库臃肿，下载慢	加入 .gitignore，只推源码
合并 PR 后忘记删除分支	分支堆积，难以管理	PR 合并页面勾选删除分支

卡点急救

1. push 报错 403/401：认证失败，检查 Token 是否过期、是否有 repo 权限。重新生成 Token 并更新凭据（Windows 在凭据管理器，Mac 在钥匙串）。
2. 合并冲突在 PR 里：GitHub 网页会提示 "This branch has conflicts"，拉到本地解决冲突后 push，PR 状态自动更新。
3. clone 太慢或失败：国内网络问题，换 SSH 方式、挂代理，或使用镜像（如 gitee 导入后再 clone）。
4. Pages 显示 404：确认仓库设置里 Pages 已启用，且 index.html 存在于部署目录的根目录。路径区分大小写。

面试常问

• git fetch 和 git pull 的区别？ fetch 只下载远程更新，不合并；pull 是 fetch + merge。想先看改了什么再决定合并用 fetch，日常同步用 pull。

• fork 工作流是什么？ 开发者 fork 上游仓库到自己的账号，在 fork 里开发，通过 PR 把改动提回上游。上游更新后，通过 git remote add upstream + git pull upstream main 同步。

• 怎么撤销已经 push 到远程的提交？ 首选 git revert <hash> 生成反向提交，安全可追踪。不要对已 push 的公共分支用 git reset --hard 或 git push -f，会改写团队共享的历史。

• GitHub Actions 是干什么的？ CI/CD 平台：代码 push 后自动跑测试、构建、部署。比如 push 到 main 分支后自动部署到服务器，或 PR 提交时自动跑单元测试。

自测三问

1. 把本地仓库第一次推送到 GitHub 需要哪几条命令？
2. 日常协作时，为什么不应该直接在 main 分支上 push？正确的流程是什么？
3. GitHub Pages 的部署地址格式是什么？如果显示 404 应该检查哪些地方？

小结一句话

GitHub 是代码的云端总部：push 同步进度、PR 审查质量、Pages 发布成果——掌握这三件事，你就从单机开发进入了协作开发的世界。

延伸

• GitHub Docs 中文
• 下一课：npm——管理前端依赖，让项目像搭积木一样组装。