从零到上线：4 周把 GitHub 变成肌肉记忆（一份小白生还指南）

👉 一句话总结

4 周、每周 2–3 小时，从「git 是啥都说不清」到拥有上线网站 + 完整 PR 流程 + 自动化 CI + 正式 Release。

不是学完一门课，而是养成肌肉记忆。

🎯 这篇文章写给谁

听说过 GitHub，但每次打开就想关掉的人
收藏过 3 个教程，一个没看完的人
想要「有产出」，而不是「再学一门技术」的人
总觉得程序员的工作流很玄学的人

不适合：已经在用 PR / Actions 干活的老手，这里没新东西。

📊 4 周后你会得到的东西（量化版）

🧭 为什么是 4 周，不是 4 天也不是 4 个月

学 GitHub 最容易踩两种坑：

❌ 太快：30 分钟速通视频，第二天全忘
❌ 太慢：买系统课，第 5 章弃坑

4 周的设计哲学是 「每周一个小型完整闭环」：

周	主题	你能向别人展示什么	核心机制	时长
W0	🛠️ 环境准备	账号 + Git + VSCode 全打通	SSH / Token / 全局配置	1h
W1	🏁 第一个 Repo & 上线	一个已上线的个人网站	本地 ↔ 云端的最小闭环	2–3h
W2	🌿 分支 & PR	被合并的 PR + 解过一次冲突	分开做事、合在一起	2–3h
W3	⚙️ Actions & Release	绿色对勾的 CI + 一个 Release	仓库的「自动化机器人」	2–3h
W4	📜 开源标准 & 复盘	一份长得像那么回事的 repo	从「自己玩」到「可以发出去」	2h

每周末都有能截图发朋友圈的东西 — 这就是燃料。

🛠️ Week 0 · 环境准备（启动当晚 60 分钟）

这一步打通，后面 4 周才不会被「环境问题」反复打断。

🧠 你要建立的第一个心智模型

📖 概念清单（你需要能解释这些）

概念	一句话解释
SSH key	本机和 GitHub 的「身份证 + 通行证」，省去每次输密码
全局配置	告诉 Git「我是谁」，每次 commit 都会带上这个署名
默认分支	主线分支的名字，现代约定叫 `main`（旧仓库可能叫 `master`）

✅ 最小清单

注册 GitHub 账号（用户名建议简短、英文、用一辈子）
如果你是学生：申请 GitHub Student Developer Pack — 免费的 Copilot Pro 比什么都值
装 Git，终端跑 git --version 验证
配置全局信息（这步以后每台新电脑都要做一次）：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git config --global init.defaultBranch main

生成 SSH key 并加到 GitHub（之后 push 不再要密码）
VSCode 装 GitLens 扩展（能在编辑器里直接看每行代码是谁、什么时候、为啥改的）

🟢 通关自查

终端 git --version 有输出
终端 ssh -T git@github.com 显示 Hi 你的用户名!
VSCode 打开任何文件夹后，左侧能看到 Source Control 图标
能用自己的话解释：repo / commit / branch / push / pull

❗ 我的卡点

SSH 那步最容易卡。如果 ssh -T git@github.com 没有显示 Hi 你的用户名!，先别往下走。这一步不通，整个 4 周都会反复出问题。

🏁 Week 1 · 看到自己的网站上线（魔法时刻）

这是整个 4 周里最爽的一周。

🎯 这周建立的工作流

📖 概念清单（这周必须能解释）

概念	一句话解释
Repository (repo)	项目的「工程文件夹」，带完整历史
Commit	一次「快照 + 说明」的提交，是 Git 的最小单元
Push / Pull	把本地变化推到云端 / 把云端变化拉到本地
`.gitignore`	声明哪些文件不要被 Git 追踪（密钥、缓存、产物）
`README.md`	项目门面，给陌生人看的入口
GitHub Pages	把 repo 静态文件免费托管成网站

🪄 一个小魔法

建 repo 时，名字一定要是 你的用户名.github.io — 这个名字会触发 GitHub 自动开启 Pages 托管。免费、自动、HTTPS。

✅ 这周的最小闭环

建一个叫 用户名.github.io 的 repo（勾选 Add README）
git clone git@github.com:用户名/用户名.github.io.git 到本地
写一个 index.html（让 AI 帮你起骨架就行）
git add . → git commit -m "feat: 添加首页" → git push
打开 https://用户名.github.io — 看到自己的网站 ✨
截图存档（这一刻你要记一辈子）
再做 3 次小 commit，练习「小 commit」习惯

❗ 这周最重要的习惯：Commit 要小，Message 要清楚

烂 message（半年后看自己代码像看天书）：

git commit -m "update"
git commit -m "fix"
git commit -m "改了点东西"

好 message（Conventional Commits 格式，下方有完整速查）：

git commit -m "feat: 添加首页自我介绍"
git commit -m "fix(nav): 修复手机端菜单错位"
git commit -m "docs: 更新 README quick start"

🌿 Week 2 · 分支 & PR（程序员协作的核心）

🧠 一个关键的认知翻转

📖 概念清单

概念	一句话解释
Branch	从某个时间点分出来的「平行宇宙」
Pull Request (PR)	申请把我的分支合并回主线，附带「同行检查」环节
Merge / Rebase / Squash	合并的三种姿势（细节见下）
Conflict	两边都改了同一行 → Git 没办法替你决定，求你手动选
Code Review	合并前的同行检查，哪怕只是自己 review 自己

⚙️ Merge 三姿势速懂

Merge：保留两条历史，多出一个「合并 commit」 — 历史最真实但乱
Squash：把分支上所有 commit 压成 1 个再合 — 历史最干净，个人项目推荐
Rebase：把分支的 commit 「重新接到」主线最新位置 — 历史像直线，但操作稍复杂

✅ 一次完整 PR 流程

# 1. 从 main 切一个新分支
git checkout -b feat/projects-page

# 2. 改东西，拆成 3–5 个小 commit
git add . && git commit -m "feat: 添加作品页骨架"
git add . && git commit -m "style: 调整作品页配色"

# 3. 推到云端（第一次推要 -u 关联远程分支）
git push -u origin feat/projects-page

# 4. GitHub 点 "Compare & pull request"
# 5. PR 标题用 Conventional 格式
# 6. PR 描述写：做了什么 + 为什么 + 怎么测
# 7. 自己 review 自己的 diff（认真挑刺）
# 8. Squash & Merge

🔥 必须亲身经历一次的事：解决 Conflict

第一次看到 CONFLICT (content): Merge conflict in ... 时，千万不要 panic 用 git reset --hard。

正确姿势：

VSCode 会自动用上下箭头标出冲突区，给你 4 个按钮：
- Accept Current：保留我这边的
- Accept Incoming：用对面那边的
- Accept Both：两个都留下
- Compare Changes：先看 diff 再决定
选完 → 保存 → git add . → git commit

🧪 这周建议练 4 个 PR

PR #1：加一个作品页（练完整流程）
PR #2：故意制造冲突再 resolve（这是必修课）
PR #3：加博客模板
PR #4：优化样式 / 配色

顺便去 Settings → Branches → Add rule 保护 main，禁止直接 push — 强制自己走 PR 流程。

⚙️ Week 3 · Actions & Release（让仓库「活」起来）

这周的关键词：自动化 + 版本管理。

🧠 心智模型

📖 概念清单

概念	一句话解释
Issue	所有「待办 / bug / 想法」的统一入口，比微信收藏强 100 倍
Label / Milestone	Issue 的分类标签和阶段目标
Workflow	一个 YAML 文件 = 一个自动化任务
Job / Step	Workflow 的两层结构：一个 job 里有多个顺序执行的 step
Tag	给某个 commit 钉一个永久标签，通常用来标版本
Release	基于 Tag 的「正式发布」，可以挂下载文件和 release notes

⚙️ 典型 Actions 应用

每次 push 自动检查代码语法
每次合并自动部署到服务器
每周一自动跑一次依赖更新
PR 评论里有人写 /deploy 就自动触发部署

✅ 你的第一个工作流 · `check.yml`

在 repo 里新建 .github/workflows/check.yml，复制下面这段进去：

# .github/workflows/check.yml
# 作用：每次 push / PR 时自动检查 HTML 语法 + Markdown 链接
name: Check

on:                              # 什么时候触发
  push:
    branches: [main]             # 推送到 main 时
  pull_request:                  # 有 PR 时
  workflow_dispatch:             # 允许手动点按钮触发

jobs:
  html-validate:                 # job 名字，随便起
    runs-on: ubuntu-latest       # 跑在什么机器上（GitHub 免费提供）
    steps:
      - name: Checkout code      # 第 1 步：把代码下载到这台虚拟机
        uses: actions/checkout@v4

      - name: Setup Node.js      # 第 2 步：装 Node（检查工具需要）
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Validate HTML       # 第 3 步：跑 HTML 检查
        run: npx html-validate "**/*.html"

      - name: Check Markdown links  # 第 4 步：检查文档里的死链
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: 'yes'

push 之后去 Actions tab 看 — 当你看到那个绿色 ✅ 的瞬间，你会明白为什么程序员对 CI 这么着迷。

🔍 跑红了怎么办？

点进那条红的记录 → 点 Re-run 之前先看日志
日志从下往上看（错误信息通常在最后几行）
拼拷贝错误记录丢给 AI，问「这是什么意思？怎么修？」— 比自己猜快 10 倍

📌 Issue + Milestone + PR 的连环技

开 3 个 Issue：1 个 bug + 1 个 feature + 1 个 chore
建一个 Milestone「v0.1.0」把它们都归进去
修 bug 时切分支 → 写代码 → 开 PR
PR 描述里写 Closes #1 — 合并时 GitHub 会自动关掉这个 Issue 🎉

🏷️ Semantic Versioning（语义化版本）

版本号是个简单约定：v主版本.次版本.修订号

变化	含义	例子
修订号 +1	修了个 bug，向后兼容	`v0.1.0` → `v0.1.1`
次版本 +1	加了新功能，向后兼容	`v0.1.1` → `v0.2.0`
主版本 +1	大改，可能不兼容旧版	`v0.2.0` → `v1.0.0`

打第一个 tag：

git tag v0.1.0
git push origin v0.1.0

然后在 GitHub Releases 页面点 Draft new release — 这是给世界看的「正式版本」。Conventional Commits 还能让你一键自动生成 release notes。

📜 Week 4 · 开源标准（从「自己玩」到「可以发出去」）

一个「专业仓库」该有的标配文件：

文件	作用	没它的代价
`README.md`	项目门面：这是什么 / 怎么用 / 找谁问	陌生人 30 秒内关掉你的 repo
`LICENSE`	声明开源协议，建议选 MIT	别人不敢用你的代码（法律风险）
`CONTRIBUTING.md`	别人怎么给你贡献代码的规则	PR 来一个乱一个
`.github/ISSUE_TEMPLATE/`	让别人提 bug / 提议有模板可循	收到一堆「能不能修一下啊」的 Issue
`.github/PULL_REQUEST_TEMPLATE.md`	让 PR 描述格式统一	review 时找不到上下文
`CHANGELOG.md`	每个版本改了什么	用户升级时一脸懵

配齐之后去 repo 的 Insights → Community Standards 看 — 全绿就说明你的项目已经「长得像那么回事」了。

📄 PR 模板 · `.github/PULL_REQUEST_TEMPLATE.md`

建一次，以后每个新 PR 都会自动填这个骨架：

## 这个 PR 做了什么
<!-- 一句话总结 -->

## 为什么要这么改
<!-- 背后的动机 / 解决的问题 -->
Closes #<!-- issue 号 -->

## 怎么测试
<!-- reviewer 怎么验证你这个改动能跑 -->
- [ ] 本地 `npm run dev` 能启动
- [ ] 访问 /xxx 页面，看到 yyy
- [ ] CI 全绿

## 截图 / 录屏（UI 改动必填）
<!-- 拖拽图片进来 -->

## 检查清单
- [ ] 代码能跑起来
- [ ] 添加/更新了必要的文档
- [ ] commit message 符合 Conventional Commits
- [ ] 没有 commit 进来密码/密钥

🐞 Issue 模板 · `.github/ISSUE_TEMPLATE/`

建两个文件，让别人提 Issue 时能选「报 bug」还是「提议新功能」。

bug_report.md

---
name: 🐞 Bug 报告
about: 遇到不对劲的行为请汇报
title: "[Bug] "
labels: bug
---

## 什么问题
<!-- 一行话描述 -->

## 复现步骤
1. 打开 ...
2. 点击 ...
3. 看到 ...

## 预期 vs 实际
- 预期：
- 实际：

## 环境
- OS： (Windows 11 / macOS 14 / …)
- 浏览器： (Chrome 120 / …)
- 版本： (v0.2.0)

## 截图 / 控制台报错

feature_request.md

---
name: ✨ 功能请求
about: 提议一个新功能
title: "[Feature] "
labels: enhancement
---

## 想解决的问题
<!-- 你为什么需要这个功能 -->

## 期望的方案
<!-- 希望怎么实现 -->

## 替代方案
<!-- 考虑过哪些别的思路 -->

## 补充上下文

🤝 CONTRIBUTING.md 骨架

个人项目不需要写太复杂，这个最小版就够：

# 贡献指南

感谢考虑给这个项目贡献！

## 提交 Issue 前
- 先搜一下是不是已经有人提过
- 用 Issue 模板，信息越全 reviewer 越快处理

## 提交 PR 的流程
1. Fork 这个 repo
2. 从 `main` 切一个 feature 分支：`git checkout -b feat/my-feature`
3. 提交改动，遵守 [Conventional Commits](https://www.conventionalcommits.org/)
4. 推到你的 fork，开 PR 回本 repo 的 `main`
5. 等 CI 跑绿 + 响应 review 评论

## 代码风格
- HTML/CSS 用 2 个空格缩进
- 文件名全小写，单词间用 `-` 分隔
- 提交前本地跑一下 `npx html-validate "**/*.html"`

## 行为准则
保持友善、耐心、尊重。他人可能是第一次贡献开源。

🚫 `.gitignore` 起手范例

项目一开始就把这个文件加进去，避免垃圾文件污染仓库：

# 依赖
node_modules/

# 环境变量 / 密钥（重点！）
.env
.env.local
*.pem
*.key

# 编辑器
.vscode/
.idea/
*.swp
.DS_Store

# 构建产物
dist/
build/
*.log

# 缓存
.cache/
.next/

🎨 README 加分项

顶部加 badges（构建状态 / license / 版本号），例如：

![CI](https://github.com/用户名/repo名/actions/workflows/check.yml/badge.svg)
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/github/v/release/用户名/repo名)

加截图 / GIF 演示（推荐用 LICEcap 录小 GIF）
加 Quick Start 章节（让人能在 3 分钟内跑起来）

❗ 10 个新手最容易踩的坑（这部分价值 ≥ 全文 30%）

把密码 / API key commit 进去 — 推送后全网公开，可能被刷爆账单。.gitignore + .env，提交前默问一句「这文件能给陌生人看吗」。
直接在 main 上改东西 — 没有缓冲层，搞砸难回滚。永远从 main 切分支。
一个 commit 改 50 个文件 — 没法 review，出问题难定位。一个 commit 只做一件事。
commit message 写 “update” / “fix” — 半年后看自己代码像看天书。用 Conventional Commits。
git push --force 不看后果 — 把别人或自己的提交直接抹掉。个人 repo 之外永远不 force push。
不先 pull 就 push — 触发冲突或被拒。改之前先 pull，写之前先 pull。
把 node_modules / 编译产物 commit 进去 — 仓库爆炸到几百 MB。.gitignore 第一天就配好。
忘了 LICENSE — 别人不敢用你代码。个人项目选 MIT，复制粘贴。
PR 标题写「改了点东西」 — reviewer 一脸懵。标题 = 做了什么；描述 = 为什么 + 怎么测。
看到 conflict 就 panic 用 git reset --hard — 会丢东西。VSCode 有 conflict UI，照着点就行。

⌨️ Git 命令速查（背 80% 就够日常用）

点开查表

# 看状态
git status              # 当前有哪些改动？
git log --oneline       # 历史 commit 简洁列表
git diff                # 看具体改了什么

# 提交
git add .               # 把所有改动加入暂存
git add 文件名           # 只加某个文件
git commit -m "feat: 描述"
git commit --amend      # 修改最近一次 commit

# 远程同步
git push                # 推到远程
git pull                # 拉远程更新（= fetch + merge）
git fetch               # 只下载，不合并

# 分支
git branch              # 看所有分支
git checkout -b 名字     # 新建并切换分支
git checkout 名字        # 切换分支
git merge 名字           # 把「名字」分支合并到当前
git branch -d 名字       # 删分支

# 反悔三连
git restore 文件名       # 丢弃工作区改动
git reset --soft HEAD~1 # 撤销最近 commit，保留改动
git revert <hash>       # 用新 commit 抵消旧 commit（安全）

📐 Conventional Commits 速查

让 commit message 一眼能读

格式：<类型>(<范围>): <描述>

类型	含义	示例
`feat`	新功能	`feat(blog): 添加文章页面`
`fix`	修 bug	`fix(nav): 修复手机端菜单错位`
`docs`	仅文档变化	`docs: 更新 README quick start`
`style`	格式（不影响逻辑）	`style: 统一缩进`
`refactor`	重构（不改功能）	`refactor: 抽取 Header 组件`
`perf`	性能优化	`perf: 压缩首页图片`
`test`	测试相关	`test: 添加导航单测`
`chore`	杂活（构建配置等）	`chore: 升级 Actions 版本`

📖 术语表（看完能听懂 90% 程序员对话）

点开查表
- Repo (Repository) — 项目仓库
- Clone — 把云端 repo 抓到本地
- Fork — 把别人的 repo 复制一份到自己账号
- Origin — 默认远程仓库别名
- HEAD — 「你当前位置」指针
- Staging Area — git add 之后、git commit 之前的中间区
- Working Directory — 你看到的文件
- Upstream — 上游分支（push 默认推到这里）
- PR (Pull Request) — 申请合并代码
- MR (Merge Request) — GitLab 的叫法，同 PR
- CI/CD — Continuous Integration / Delivery，自动化测试 + 部署
- SemVer — Semantic Versioning，v1.2.3
- Octocat — GitHub 吉祥物（章鱼猫）

🎁 4 周后你会得到什么

实物：上线网站 / 15+ commit / 4+ PR / 1 个 Actions / 1 个 Release / 一份「开源级」repo

更重要的：

不查文档完成 commit → push → PR
看到 conflict 不慌
能用人话向小白讲清楚 10 个核心概念
知道一个项目「长什么样算专业」

🎯 给下一个你的最后建议

不要追求完美的第一周。第一次的 HTML 很丑、第一次的 commit message 很烂、第一次的 PR 描述很短 — 都正常。先完整跑通，再回头优化。
每周末写一句话复盘：这周最不熟悉的命令是什么？卡在哪？怎么解决的？这些笔记 6 个月后会救你命。
不要一个人闷着学。AI 现在是最好的 24h Git 助教 — 卡住就问，问的过程本身就是学习。
完成后给自己一个仪式感：截图、发朋友圈、写一篇博客（比如就像这篇）。让胜利被看见，下一个项目才会启动。

🚀 4 周之后，下一步去哪里

你已经超过 80% 的「AI 时代参与者」。可以走的下一步：

把这个项目放进简历 / 个人简介
给某个开源项目提第一个 PR（推荐：从修 typo 开始，门槛最低）
启动第二个项目 — 这次用 Python 写个小工具，巩固肌肉记忆
把这套笔记开源出去，帮下一个小白少走弯路

👉 一句话总结

🎯 这篇文章写给谁

📊 4 周后你会得到的东西（量化版）

🧭 为什么是 4 周，不是 4 天也不是 4 个月

🛠️ Week 0 · 环境准备（启动当晚 60 分钟）

🧠 你要建立的第一个心智模型

📖 概念清单（你需要能解释这些）

✅ 最小清单

🟢 通关自查

❗ 我的卡点

🏁 Week 1 · 看到自己的网站上线（魔法时刻）

🎯 这周建立的工作流

📖 概念清单（这周必须能解释）

🪄 一个小魔法

✅ 这周的最小闭环

❗ 这周最重要的习惯：Commit 要小，Message 要清楚

🌿 Week 2 · 分支 & PR（程序员协作的核心）

🧠 一个关键的认知翻转

📖 概念清单

⚙️ Merge 三姿势速懂

✅ 一次完整 PR 流程

🔥 必须亲身经历一次的事：解决 Conflict

🧪 这周建议练 4 个 PR

⚙️ Week 3 · Actions & Release（让仓库「活」起来）

🧠 心智模型

📖 概念清单

⚙️ 典型 Actions 应用

✅ 你的第一个工作流 · check.yml

🔍 跑红了怎么办？

📌 Issue + Milestone + PR 的连环技

🏷️ Semantic Versioning（语义化版本）

📜 Week 4 · 开源标准（从「自己玩」到「可以发出去」）

📄 PR 模板 · .github/PULL_REQUEST_TEMPLATE.md

🐞 Issue 模板 · .github/ISSUE_TEMPLATE/

🤝 CONTRIBUTING.md 骨架

🚫 .gitignore 起手范例

🎨 README 加分项

❗ 10 个新手最容易踩的坑（这部分价值 ≥ 全文 30%）

⌨️ Git 命令速查（背 80% 就够日常用）

📐 Conventional Commits 速查

📖 术语表（看完能听懂 90% 程序员对话）

🎁 4 周后你会得到什么

🎯 给下一个你的最后建议

🚀 4 周之后，下一步去哪里

✅ 你的第一个工作流 · `check.yml`

📄 PR 模板 · `.github/PULL_REQUEST_TEMPLATE.md`

🐞 Issue 模板 · `.github/ISSUE_TEMPLATE/`

🚫 `.gitignore` 起手范例