刚打开 GitHub 时,仓库首页、分支、Issue、Pull Request 和 Actions 会同时出现在眼前。先不急着把所有功能都学完,可以沿着一次完整使用过程往下走:把项目放到本地,知道怎样保存修改,找到感兴趣的代码,再把自己的改动提交回去。
下面从账号与 Git 配置开始,逐步讲到项目搜索、源码阅读、PR、自动检查和静态网站发布。命令与网页操作放在同一步里,读到哪里就能对照做哪里;最后保留常见问题和命令速查,方便以后回来查。
01 · Git 与 GitHub
Git 是管理文件版本的工具,在本地就能记录改动、查看历史和切换分支。GitHub 则用来托管 Git 仓库,并提供问题讨论、代码评审和自动任务。两者经常一起使用,但并不是同一个东西。
例如你在电脑上修改 README,运行 git commit 后,这次改动已经记进本地仓库,GitHub 网页还不会跟着变化。继续运行 git push,提交才被送到远程仓库。先分清本地与远程,遇到“明明提交了,网页怎么没更新”时就知道该检查哪一步。

02 · 注册、安装与配置身份
进入 GitHub,点击 Sign up,按页面完成注册并验证邮箱。注册完成后,到账号设置中开启双重验证,把恢复码保存在自己能妥善找回的位置。
账号准备好以后,还要在电脑上安装 Git。网页账号负责远程身份,本地 Git 负责处理项目文件;下面的命令在终端中执行。

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 的都是公钥,私钥留在自己的设备上。

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。

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。下面将这段本地操作连起来:


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 标签,选择这次运行,再进入具体 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 执行构建后部署。先确认本地能够生成静态文件,再把同样的构建过程搬到工作流中。

首次部署等待构建完成,再检查发布地址。自定义子域名在 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 当月的免费分钟也不会累加到下个月。先看用量,再决定任务频率和资源规格。

12 · 用同名仓库设置主页
GitHub 个人主页可以展示一份特殊 README。新建公开仓库,名称与自己的用户名完全相同,在仓库根目录加入 README.md,提交后即可在个人主页中查看效果。
内容可以先写得简单:自己正在做什么、有哪些项目值得看,以及愿意公开的联系渠道。项目名称配一句说明和链接,让点进主页的人能够继续找到代码。以后项目有了变化,再更新这份文件即可。


# 你好,我是你的名字
正在做:项目名称和一句说明
- 项目:[项目地址](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 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 操作。

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

原帖出处:想风 @xaiwind · GitHub教程。本文按15个主题展开讲解,保留操作路径、命令功能与19张原帖配图;封面沿用网站现有插图。
核对说明(2026-10-06):原帖的私有协作者3人限制、用户名不可修改、恢复码只可看一次及旧系统计费倍率不作现行规则。参考 Git配置、GitHub Flow、Pages、Actions计费。



