FIELD NOTES 工具推荐

GitHub 入门:配置、读源码与协作流程

从Git配置与SSH/PAT认证,到搜索、读源码、PR、Actions、Pages和团队分支规则,附命令、页面路径与原帖配图。

GitHub 入门:从第一份项目开始。深色桌面上的笔记本电脑,青色分支与提交节点汇合到一个网页面板。
工具推荐X YOUMIN / FIELD NOTES

刚打开 GitHub 时,仓库首页、分支、Issue、Pull Request 和 Actions 会同时出现在眼前。先不急着把所有功能都学完,可以沿着一次完整使用过程往下走:把项目放到本地,知道怎样保存修改,找到感兴趣的代码,再把自己的改动提交回去。

下面从账号与 Git 配置开始,逐步讲到项目搜索、源码阅读、PR、自动检查和静态网站发布。命令与网页操作放在同一步里,读到哪里就能对照做哪里;最后保留常见问题和命令速查,方便以后回来查。

01 · Git 与 GitHub

Git 是管理文件版本的工具,在本地就能记录改动、查看历史和切换分支。GitHub 则用来托管 Git 仓库,并提供问题讨论、代码评审和自动任务。两者经常一起使用,但并不是同一个东西。

例如你在电脑上修改 README,运行 git commit 后,这次改动已经记进本地仓库,GitHub 网页还不会跟着变化。继续运行 git push,提交才被送到远程仓库。先分清本地与远程,遇到“明明提交了,网页怎么没更新”时就知道该检查哪一步。

原帖配图:Git 与 GitHub 的区别

02 · 注册、安装与配置身份

进入 GitHub,点击 Sign up,按页面完成注册并验证邮箱。注册完成后,到账号设置中开启双重验证,把恢复码保存在自己能妥善找回的位置。

账号准备好以后,还要在电脑上安装 Git。网页账号负责远程身份,本地 Git 负责处理项目文件;下面的命令在终端中执行。

原帖配图:GitHub 注册入口

macOS 已安装 Homebrew 时:

brew install git
git --version

Windows 从 Git 官网 安装,再打开 Git Bash。配置提交者信息:

git config --global user.name "你的名字"
git config --global user.email "你的GitHub关联邮箱"
git config --list

user.name 与 user.email 会写进之后的提交记录。邮箱使用 GitHub 已关联的地址,提交才容易对应到个人主页;希望隐藏常用邮箱,也可以填写 GitHub 提供的 noreply 地址。

这里配置的是提交署名,不是登录凭据。即使署名填好了,推送时仍需要通过 SSH 或 HTTPS 认证;这两条路径会在下一节配置。--global 表示这份设置作为当前用户各仓库的默认值。

03 · 仓库、提交、分支、远程与认证

初始化和提交

新项目从一个文件夹开始。进入目录执行 git init,Git 就会在其中创建保存版本记录的 .git 目录。此后可以用 git status 查看哪些文件新建了、哪些被修改了。

在编辑器中新建并保存 README.md,写上项目说明,再执行下面的 add 与 commit。add 把指定文件的当前变化加入待提交范围,commit 将这一批变化保存成一条历史记录。

mkdir my-project
cd my-project
git init
git status
# 创建或修改文件之后:
git add README.md
git commit -m "添加项目说明"

提交后再运行一次 git status,看看是否还有未提交的文件。一个项目中可能同时修改了多个文件,git add README.md 只选择其中这个文件;git add . 则会暂存当前目录范围内符合条件的改动。初学时先明确写出文件名,更容易看清每次提交包含什么。

.git 中保存的是版本历史和仓库配置,不是可以随手清理的缓存。想检查变化,用 git diff;想确认提交是否存在,用 git log,不需要手动改动 .git 内的文件。

分支与远程

分支让一项改动有独立的推进位置。先查看当前分支,再从它新建 feature-x,在这个分支修改并提交。完成以后,切回主分支,再将这项改动合并进去。

下面的示例假定主分支名是 main。若刚初始化的仓库显示为其他名称,可在首次提交后用 git branch -M main 统一名称,或在后续命令中使用实际分支名。

git branch
git switch -c feature-x
# 完成修改并提交之后:
git switch main
git merge feature-x
git remote add origin https://github.com/你的用户名/仓库名.git
git push -u origin main

网页端先创建对应的空仓库,再把它的地址填到 git remote add origin 后面。origin 是这份远程连接的名字;git push -u origin main 将本地 main 推过去,并建立后续推送时使用的对应关系。

已从 GitHub 克隆下来的仓库通常已有 origin,可以先运行 git remote -v 查看,不必重复添加。示例使用 HTTPS 地址;如果采用下面的 SSH 认证,远程地址也应使用仓库 Code 菜单里的 SSH 格式。

SSH 公钥路线

ssh-keygen -t ed25519 -C "你的邮箱"
# 公钥文件通常是 ~/.ssh/id_ed25519.pub
ssh -T git@github.com

先运行 ssh-keygen 生成密钥。若提示目标文件已存在,先检查自己是否已有要继续使用的密钥,避免覆盖。随后打开对应的 .pub 公钥文件,把内容复制到 GitHub 头像 → Settings → SSH and GPG keys → New SSH key。

保存后再运行 ssh -T git@github.com 测试认证。认证完成后,从仓库 Code 菜单复制 SSH 地址用于克隆,或将已有 origin 改为对应的 SSH 地址。原帖也展示了 RSA 3072 位方案,通常对应 ~/.ssh/id_rsa.pub;不论采用哪种算法,添加到 GitHub 的都是公钥,私钥留在自己的设备上。

原帖配图:SSH 公钥设置页

HTTPS / PAT 路线

如果远程地址使用 HTTPS,就配置对应的凭据。进入 Settings → Developer settings → Personal access tokens,选择令牌类型,再设置名称、到期时间、可以访问的仓库和权限。

生成后把令牌放到凭据管理器中保存。后面终端通过 HTTPS 请求认证时,使用令牌而不是 GitHub 账号密码;不必把令牌直接写进仓库 URL 或脚本。权限按要做的事情配置,下面是原帖涉及的两种类型:

  • Fine-grained:选定仓库,按推送需求设置 Contents: Read and write;Metadata 为必要读取权限。
  • Classic:原帖使用 repo 范围;这是较宽权限,应按实际任务限制访问。
  • HTTPS 提示输入密码时用 PAT,不用 GitHub 账号密码。凭据交给凭据管理器,不拼进仓库 URL。

原帖配图:PAT 管理入口,图示权限不是默认推荐配置

04 · 看项目首页

进到一个仓库,先读 README,了解它做什么、怎样运行。右上角的 Star 可以帮助你收藏项目,Watch 用来控制更新通知;两者都不会把项目文件复制到自己的电脑。

想在自己账号下保留一份可修改的仓库,使用 Fork。发现问题或有功能建议,进入 Issues 讨论;已经修改了代码,希望维护者接收改动,则提交 Pull Request。

PR 里不只有最终代码。打开 Files changed 可以逐行看新增和删除,评论中能看到维护者要求怎样调整。找一个已合并的小 PR 读完,往往比只看项目当前文件更容易理解一次改动是怎样完成的。

原帖配图:仓库首页的功能入口

找贡献入口时,查看 good first issue 与 help wanted 标签。提问题前先搜已有 Issue。

05 · 搜索仓库与代码

限定符 用途
in:name / in:readme 限定仓库名或说明文档
language:go 限定语言
stars:>500 筛选星标数量
pushed:>2026-01-01 筛选最近推送时间
topic:self-hosted 按主题寻找
user:用户名 搜索指定用户的仓库

这些限定符可以叠加。例如想找 Go 写的聊天项目,再用星标数和最近更新时间缩小范围,就把条件一起写进搜索框。搜索结果出来后,继续看 README、维护活动和许可证,判断项目是否适合自己的用途。

组合示例:

chat language:go stars:>500 pushed:>2026-01-01
is:issue is:open label:"good first issue"

原帖配图:组合搜索结果

搜实现时切换到 Code,例如 cloudflared language:yaml,代码搜索需要登录。还没确定工具时,可以先看 awesome 类清单和 Topics。

06 · 五步读源码

第一步:从 README 建立整体印象

先弄清用途、运行环境和 Quick Start。项目解决什么问题,安装依赖之前还要配置什么,启动以后从哪个地址或命令进入,都先在说明文档里找。遇到不熟悉的目录,不需要此时逐个打开。

第二步:把项目运行起来

按说明安装依赖、准备配置,再启动项目,实际操作一个小功能。能够描述“我做了什么,页面或终端出现什么结果”,后面阅读代码时就有明确对象,而不是对着整个目录猜。

第三步:找到程序入口

不同语言的入口位置不同。Go 常从 main.go 开始,Python 可能是 __main__.py、app.py 或 manage.py,Node 先看 package.json 中的 scripts;PHP 可从 public/index.php 查看,Rust 则看 src/main.rs。入口文件帮助你找到初始化和功能注册的位置。

第四步:只追一条功能链

挑刚才实际操作过的功能,从按钮或请求开始,顺着路由找到处理函数,再看它怎样查询数据、组织结果和返回响应。一次只跟这一条链,旁边不相关的模块先放着。这样能把运行时看到的结果,与具体代码对应起来。

第五步:回到历史和测试补充原因

遇到不理解的写法,查看对应文件的 Commits、Blame 和相关 PR,了解它在哪次修改中加入。测试目录及 _test.go 之类的文件,可以帮助你观察输入、返回值和边界情况。测试和历史提供的解释,常常是只看当前函数时缺少的部分。

网页里按 t 可以快速找文件,按 . 打开网页编辑器后,用 Cmd+P 或 Ctrl+P 跳转文件。先掌握这些导航方式,阅读时就不用反复在目录中展开和折叠。

原帖配图:围绕一条功能链阅读源码

07 · 从 Fork 到第一个 PR

先查看项目有没有 CONTRIBUTING.md,确认分支、测试和提交要求。选一项范围小的修改,例如修正文档链接,然后在原仓库点击 Fork,得到自己账号下的副本。

回到自己的 Fork,在 Code 菜单复制克隆地址。克隆的是自己名下的仓库,之后才能将分支推到这份副本,再请求原仓库接收。克隆完成后新建修改分支,不直接把所有改动都堆在主分支上。

修改与检查完成,依次 add、commit、push,网页一般会出现 Compare & pull request。点进去后确认目标仓库是原项目、目标分支符合项目要求,来源则是自己刚推送的修改分支。描述中写清改了什么、为什么改、怎样检查。

维护者提出修改意见时,继续在同一个分支调整、提交并推送,原 PR 会自动更新,不需要为每次调整新建一个 PR。下面将这段本地操作连起来:

原帖配图:PR 流程

原帖截图:Code 菜单与 HTTPS 克隆地址

git clone https://github.com/你的用户名/项目名.git
cd 项目名
git switch -c docs/fix-link
# 编辑 README.md,并完成检查
git diff
git add README.md
git commit -m "修复文档链接"
git push -u origin docs/fix-link

PR 描述按“改动 / 原因 / 检查结果”填写,确实解决对应 Issue 时可写 Closes #123。只为浏览下载时可以用 --depth 1 浅克隆;需要完整历史和上游协作时使用普通克隆。

原项目继续更新时,自己的 Fork 可能落后。把原仓库添加为 upstream,先取回它的新提交,再切回本地主分支合并,最后推送到自己的 origin。如果遇到冲突,先处理冲突并检查,再继续推送。

只需添加一次 upstream;已有时先用 git remote -v 查看。以下命令假设原项目的主分支也是 main:

git remote add upstream https://github.com/原作者/项目名.git
git fetch upstream
git switch main
git merge upstream/main
git push origin main

08 · Actions:添加一个自动任务

Actions 可以在推送或提交 PR 后自动执行一组操作。先把需要执行的测试在本地跑通,再写进工作流,调试时容易判断是测试本身失败,还是自动运行环境缺了东西。

在仓库中创建 .github/workflows/check.yml。下面的例子遇到 push 或 pull_request 时,在 Ubuntu 执行器上检出仓库并查看状态;它只演示工作流结构,不代表已经对业务代码做了测试。实际使用时把 run 后面的命令换成自己的检查命令:

name: Check
on: [push, pull_request]
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: git status --short

原帖配图:Actions 自动化

将文件提交并推送后,打开仓库 Actions 标签,选择这次运行,再进入具体 job 查看每一个 step 的输出。绿色表示该步骤完成,失败时展开日志,从末尾向上找最早出现的具体错误;exit code 1 只是结束状态,原因通常在前面的输出里。

任务需要令牌或其他密钥时,到 Settings → Secrets and variables → Actions 中配置,再通过 ${{ secrets.NAME }} 引用。工作流文件本身会跟随仓库保存,敏感值不直接写进 YAML。

公开仓库的标准托管执行器可免费使用;GitHub Free 私有仓库包含每月2,000分钟及500MB artifact存储。超额、较大执行器和其他存储另按计费规则处理,具体价格见文末官方链接。

09 · Pages:把静态文件发布成网站

个人站可以新建名为 你的用户名.github.io 的仓库,把 index.html 和其他静态资源放进去,再配置 Pages。项目站则使用普通仓库,发布地址通常带上项目名称,文件中的资源路径也要与部署位置相符。

从分支发布时,打开 Settings → Pages,在 Source 选择 Deploy from a branch,再选择要发布的分支和目录。网页在仓库根目录就选 /(root),在 docs 目录就选 /docs,保存后等待部署完成。

使用 Hugo、Hexo 或 VitePress 一类工具时,源文件还要经过构建,可以改用 Actions 执行构建后部署。先确认本地能够生成静态文件,再把同样的构建过程搬到工作流中。

原帖配图:GitHub Pages

首次部署等待构建完成,再检查发布地址。自定义子域名在 Custom domain 填入,并在 DNS 配置 CNAME 指向 你的用户名.github.io,验证完成后开启 Enforce HTTPS;根域名配置按官方 DNS 指引处理。Pages 提供静态托管,不运行常驻后端。

10 · 七类常见问题

原帖配图:常见问题

问题 排查与处理
.env 或密钥入库 先撤销泄露凭据,再清理历史;.gitignore 不会删除已提交历史
大文件推送失败 查找超大文件;普通Git单文件100MiB限制,适合的二进制素材改用Git LFS
提交身份不匹配 git config user.email,核对已验证邮箱或noreply地址
主分支改乱 先保存工作区,使用分支或 git stash -u;确认后才做会丢弃数据的操作
Fork落后 添加upstream,fetch后合并,再push自己副本
2FA设备丢失 使用事先保存的恢复码或已配置的其他恢复方式
upstream返回404 检查地址、仓库可见性和访问权限,不反复盲目推送
find . -type f -size +100M
git lfs install
git lfs track "*.psd"
git add .gitattributes

11 · 免费资源与用量

GitHub 中的仓库、Actions、Pages、Codespaces 和 Copilot 是不同功能,使用量也分别计算。需要在线开发环境时看 Codespaces,需要持续运行的自动任务时看 Actions,不要把某一项免费额度理解成整个账号任意使用都免费。

到账号 Billing / Usage 中查看当前消耗与额度。Codespaces 停止后仍然保留文件,不再需要的环境可以删除以结束相应存储占用;Actions 当月的免费分钟也不会累加到下个月。先看用量,再决定任务频率和资源规格。

原帖配图:GitHub 工具箱

12 · 用同名仓库设置主页

GitHub 个人主页可以展示一份特殊 README。新建公开仓库,名称与自己的用户名完全相同,在仓库根目录加入 README.md,提交后即可在个人主页中查看效果。

内容可以先写得简单:自己正在做什么、有哪些项目值得看,以及愿意公开的联系渠道。项目名称配一句说明和链接,让点进主页的人能够继续找到代码。以后项目有了变化,再更新这份文件即可。

原帖配图:个人主页 README

原帖的工具箱配图

# 你好,我是你的名字

正在做:项目名称和一句说明

- 项目:[项目地址](https://github.com/你的用户名/项目名)
- 联系方式:你愿意公开的联系渠道

13 · 团队分支规则

多人协作时,可以采用原帖的三层分支安排。每项功能在 feature/xxx 中开发,完成后通过 PR 合到 dev 做集中测试;准备发布时,再把确认过的改动合入 main,最后打 tag 标记版本。

这套结构的意义是让开发中、待测试和准备发布的改动有明确位置。团队确定使用这套流程以后,还要在仓库设置中保护重要分支,避免有人跳过约定直接推送。

原帖配图:团队协作分支

进入 Settings → Rules → Rulesets → New branch ruleset,新建分支规则,将 Enforcement 设为 Active,目标匹配 main。按团队安排,要求改动通过 PR、评审和必要检查后才允许合并。旧版界面也可以从 Settings → Branches 设置分支保护。

配置完毕后用实际 PR 查看检查项是否与工作流对应。规则要求的是项目确实会运行的检查,分支名称也要与仓库中的实际名称一致。

14 · 命令速查

原帖配图:Git 命令速查

git status                    # 工作区状态
git log --oneline -10          # 最近提交
git diff                      # 未暂存修改
git diff --staged             # 已暂存修改
git add README.md             # 暂存指定文件
git commit -m "修改说明"       # 本地提交
git push                      # 推送
git branch                    # 分支列表
git switch -c feature/name     # 新建分支
git switch main               # 切换分支
git merge feature/name        # 合并到当前分支
git stash -u                  # 暂存含未跟踪文件的工作
git stash pop                 # 恢复暂存
git remote -v                 # 查看远程

git restore 文件名 会丢弃该文件未暂存的修改;git reset --hard HEAD~1 会重置分支并丢弃受跟踪的工作区改动。先备份、确认范围,再决定是否使用。共享分支通常使用 merge;rebase 会改写提交历史。

15 · 工具与托管平台的区别

Git 是分布式版本控制,SVN 是集中式版本控制;GitHub、GitLab、Gitee 是托管与协作平台。不要把更换托管平台理解成更换全部 Git 操作。

原帖配图:Git、SVN 与托管平台

新建仓库时依次填写 Repository name、Description、Public/Private,按需要添加 README、.gitignore 和 LICENSE,再点创建。

原帖截图:个人主页与仓库入口


原帖出处:想风 @xaiwind · GitHub教程。本文按15个主题展开讲解,保留操作路径、命令功能与19张原帖配图;封面沿用网站现有插图。

核对说明(2026-10-06):原帖的私有协作者3人限制、用户名不可修改、恢复码只可看一次及旧系统计费倍率不作现行规则。参考 Git配置、GitHub Flow、Pages、Actions计费。

这篇笔记到这里。
探索,仍在继续。

再读一篇

YOUR READING LIST

留给下次的好文章。

收藏仅保存在当前浏览器,不会上传至服务器。