GitHub 能做什么：从建仓库到 PR、Pages 和 Actions

GitHub 常被当成程序员才用的东西。其实它能放代码和主题、发静态页、挂下载文件、收反馈，也能给网站留一份备份。

第一次打开 GitHub，容易被 Code、Issues、Pull requests、Actions 这些词弄晕。这篇按一个仓库能做什么来讲，每个入口是干嘛的、网页上怎么点，尽量说清楚。

1. GitHub 是什么

Git 是版本管理工具，GitHub 是托管 Git 仓库的网站。不会 Git 命令也能用网页按钮完成大部分操作。

一个仓库就是一个项目文件夹。里面可以放代码、图片、文档，也可以只放一个 index.html。

第一次进来，先认这几个词：

仓库顶部还有一排标签：

右上角还有三个按钮：

• Star：收藏，相当于点个赞。
• Fork：把别人的仓库复制一份到你自己的账号。
• Watch：订阅这个仓库的更新通知。

仓库有两种可见性：Public 谁都能看，Private 只有登录且有权限的人能看。

它不是一个网盘。单文件超过 100MB 会被拒绝，仓库也不适合堆几万张原图。图片放对象存储或图床，GitHub 只放要版本管理的文件。

2. 建第一个仓库

登录后，点右上角的 +，选 New repository。

界面示意：仓库名、可见性和 README 填好就能创建。

需要填的只有几项：

• Repository name：仓库名，比如 my-site。
• Description：可空。
• Public 或 Private：想用免费 Pages，通常选 Public。
• Add a README file：勾上，仓库会自带一个说明文件。
• Add .gitignore：可空，建站项目一般用不上。
• Choose a license：可空，公开项目可以选 MIT。

仓库名用英文小写、数字和短横线，不要空格和中文。README 可以写项目说明，也可以只留一个标题。Public 仓库别人能看到文件和历史；Private 只有登录且有权限的人能看。

点 Create repository，仓库就建好了。默认分支通常叫 main。

仓库名会影响 Pages 的网址：

• 仓库名叫 你的用户名.github.io，网址是 https://你的用户名.github.io/。
• 仓库名叫别的，网址是 https://你的用户名.github.io/仓库名/。

README 会显示在仓库首页。点 README 右上角的铅笔图标，可以写：

# 我的站点

一个静态站点，用来放文章和下载文件。

- 首页：index.html
- 样式：style.css

Markdown 的 # 是一级标题，## 是二级标题，- 是列表。改完点 Commit changes 保存。

3. 上传和修改文件

进仓库的 Code 页，点 Add file，选 Upload files。

界面示意：Add file → Upload files，拖进去后点 Commit changes。

把文件拖进虚线框，或者点 choose your files。下面填一句提交说明，比如 Add index.html，点 Commit changes。

改文件更简单：点进文件，点右上角的铅笔图标，改完再点 Commit changes。

Commit changes 就是保存。GitHub 会保留每次修改的记录，点 History 能看到谁在什么时候改了什么。

网页上传会保留文件夹结构。不要把整个 .zip 传上去让 Pages 读，Pages 只认解压后的 HTML、CSS、JS。传错分支，先在左上角切回 main。

想下载整个仓库，点绿色的 Code 按钮，选 Download ZIP。想长期在本地改，装 GitHub Desktop，登录后把仓库 clone 下来，改完点提交、推送，不用记命令。

网页上传适合几个文件。几百个文件、整个文件夹，用 GitHub Desktop 或 Git 客户端更稳。

不要把密码、API key、服务器私钥提交进仓库。Public 仓库所有人都能看到，Private 仓库的协作者也能看到。提交记录会保留历史，删掉文件不等于删掉记录。

4. 分支和 Pull Request

分支是什么

分支是项目的另一条工作线。main 是默认分支，也是最终版本。想改东西，可以新建一条分支，在分支上改，改完再合并回 main。

好处是 main 不会被改乱。改坏了，删掉分支就行；改好了，再合并。

Pull Request 是什么

Pull Request 简称 PR，中文叫合并请求。它的作用是：把一条分支的改动，请求合并到另一条分支。

PR 不是上传按钮，也不是发布按钮。它的流程是：

1. 在分支上改文件、提交。
2. 发起 PR，选择“从哪条分支合到哪条分支”。
3. 看 Files changed，确认改了哪些行。
4. 可以逐行评论、讨论、改代码。
5. 点 Merge pull request 合并。
6. 合并后，改动才进入 main。

个人项目也能用 PR。它能把“改了什么、为什么改”留成一条记录，以后回来看得懂。

在网页上提一个 PR

假设要改 README。

第一步，建分支。

在仓库 Code 页，点左上角的分支下拉框，默认显示 main。输入新分支名，比如 update-readme，点 Create branch: update-readme。

也可以点 View all branches，再点 New branch。

第二步，在分支上改文件。

确认左上角当前分支是 update-readme，不是 main。点进 README，点铅笔，改完点 Commit changes。

提交时确认选的是 Commit directly to the update-readme branch。如果选到 main，就绕过了 PR。

第三步，发起 PR。

提交后，仓库首页通常会出现一条黄色提示，右边有 Compare & pull request，点它。

没有这条提示，就点顶部的 Pull requests，再点 New pull request。

第四步，选对方向。

• base 选 main，这是要合入的目标分支。
• compare 选 update-readme，这是你刚才改的分支。

页面会显示 Able to merge，说明没有冲突，可以自动合并。如果显示冲突，先解决冲突再继续。

填标题和说明，比如：

• 标题：更新 README 的部署说明
• 说明：补充 Pages 域名绑定步骤，修正过期的截图链接。

点 Create pull request。

界面示意：base 选 main，compare 选改动分支，确认可合并后创建 PR。

第五步，看改动。

进 Files changed，红色是删除，绿色是新增。鼠标移到行号旁边，可以点 + 写行内评论。

自己一个人的仓库，可以直接点 Merge pull request；有协作者时，可以点 Review changes，选 Approve 或 Request changes。

第六步，合并。

点 Merge pull request，再点 Confirm merge。合并后，main 上就有这次改动。

合并完可以点 Delete branch 删除这条分支。分支删了，提交记录还在，main 不受影响。

Fork 是什么

Fork 是把别人的整个仓库复制一份到你的账号。适合你没有原仓库写权限的情况。

流程是：

1. 打开原仓库，点右上角 Fork，复制到你的账号。
2. 在你自己的副本里改文件、提交。
3. 点 Contribute → Open pull request，把改动提回原仓库。
4. 原仓库作者 review 后决定合不合。

Fork 和分支的区别：Fork 是复制整个仓库，分支是在一个仓库里开一条工作线。

合并方式怎么选

点合并按钮旁边的下拉箭头，通常有三种：

• Create a merge commit：保留分支上的每次提交，历史完整。默认选这个就行。
• Squash and merge：把整条分支压成一个提交，历史更干净。改动碎、提交多时好用。
• Rebase and merge：把提交接到目标分支后面，历史是一条直线。熟悉 Git 再用。

新手用默认的 merge commit，或者 squash，都够。

PR 的几种状态

• Open：开着，等 review 或等合并。
• Draft：草稿，还没改完。建 PR 时可以选 Create draft pull request，改完点 Ready for review。
• Merged：已合并。
• Closed：没合并就关了，分支还在，可以重新开。

PR 页面下方会显示检查项。仓库开了 Actions 的话，构建、测试结果会显示在这里；检查没通过，合并按钮可能是灰的。

几条实用规则

• 一个 PR 只做一件事，标题写清楚，别把改错字和换主题混在一起。
• 提交前看一遍 Files changed，确认没有密码、token、调试代码。
• 协作者的分支不要随便 force push，会把别人的提交冲掉。
• 冲突不要怕，GitHub 会标出冲突文件，改完再提交一次。
• PR 合并前不会影响 main，也不会自动发布网站；发布要看 Pages 或 Actions 的配置。

5. 用 Pages 发布静态站

Pages 是 GitHub 自带的静态网站托管。HTML、CSS、JS、图片都能放，不支持 PHP、数据库和 WordPress。

进仓库的 Settings，左侧点 Pages。

界面示意：Settings → Pages，分支选 main，目录选根目录。

按这个顺序设置：

1. Source 选 Deploy from a branch。
2. Branch 选 main。
3. 目录选 / (root)。
4. 点 Save。

Pages 有两种发布源：Deploy from a branch 适合手写静态页，GitHub Actions 适合 Hugo、Hexo、Astro 构建后发布。刚开始用分支就行。

一个最小的静态站只要有这些文件：index.html、style.css、images/。等一两分钟，页面会给一个网址。仓库根目录要有 index.html，否则打开是 404。

Hugo、Hexo、Astro 生成的目录通常是 public 或 dist，不能直接把仓库根目录选成发布目录。把生成文件放进 docs，或者用 Actions 构建后再发布。

Pages 每次从 main 构建。PR 没合并之前，Pages 不会更新；合并后，等一次构建完成，线上才会变。

绑定自己的域名

在 Pages 页面找到 Custom domain，填 www.example.com，点保存。

然后去域名解析控制台加一条 CNAME：

• 主机记录：www
• 记录类型：CNAME
• 记录值：你的用户名.github.io

根域名 example.com 不支持 CNAME，要按 Pages 页面提示加 A 记录。解析生效后，回 Pages 页面勾选 Enforce HTTPS。

HTTPS 证书可能要等几分钟到几小时。一直 pending，检查 CNAME 有没有填错，再删掉自定义域名重新加一次。域名前面套了 Cloudflare 代理，先关掉代理再验证，证书签发会顺一些。

Pages 的限制

免费账号通常只能给公开仓库开 Pages，私有仓库要看你当前的套餐。

国内访问 GitHub Pages 可能慢，也不稳定。国内用户为主，Pages 适合当源站或备份，主站放国内对象存储加 CDN，或者 Cloudflare Pages 这类平台。

6. 用 Releases 放下载文件

仓库里的文件是源码，Releases 是正式版本。安装包、压缩包、电子书、素材包，放 Releases 更合适。

进仓库的 Releases，点 Draft a new release。

界面示意：Releases 里新建版本，把压缩包作为附件上传。

填这几项：

• Tag：版本号，比如 v1.0.0。
• Release title：版本标题，比如 第一版。
• 说明：这个版本改了什么。

Tag 是版本标记，Release 是围绕这个 tag 的说明和附件。GitHub 会自动生成 Source code 的 zip 和 tar.gz，那是源码，不是你的成品。仓库首页右侧会显示 Latest release。

把文件拖进附件区，点 Publish release。

Release 可以存草稿，也可以勾 Set as a pre-release 标成测试版。发布后，附件有独立的下载地址和下载次数，比仓库里的 raw 链接清楚。

不要拿仓库里的 raw 链接当下载地址。raw 链接是给浏览器看文件内容的，下载文件名、版本号、统计都不好管理。Releases 的附件才有正式的下载地址。

7. 用 Actions 自动构建

Actions 是 GitHub 的自动任务。推送代码、发起 PR、合并到 main，都可以触发它。它可以自动构建静态站、跑测试、发布 Pages。

进仓库的 Actions，点 New workflow，选一个 starter。

界面示意：Actions 里能看到每次构建的结果和耗时。

几个词先分清：

• Workflow：一条自动流程，配置文件放在 .github/workflows/ 里。
• Job：流程里的一项任务，比如构建、部署。
• Step：任务里的一步，比如安装依赖、执行命令。
• Runner：跑任务的机器，GitHub 提供托管机器。

常见的静态博客流程是：

1. 检出仓库。
2. 安装 Node 或 Hugo。
3. 执行构建命令。
4. 把生成目录发布到 Pages。

一个 workflow 可以有多个 job，一个 job 分成多个 step。构建失败，点进那次运行看日志，红色那一步就是出错的位置。

不会写 YAML 也能用 starter，改构建命令和输出目录就行。token、密钥放到 Settings → Secrets and variables → Actions，不要写进 YAML。

用 Actions 发布 Pages，要先把 Pages 的 Source 改成 GitHub Actions，再到 Settings → Actions → General 把 Workflow permissions 设为读写。

PR 页面下方的检查项，很多就是 Actions 跑出来的。检查没过，先点 Details 看日志，不要直接合并。

公开仓库的 Actions 一般免费，私有仓库有额度，超出会计费。用不上自动构建，就手动上传文件，Actions 不是必须的。

8. Issues 和 Discussions

Issues 适合收具体问题：哪个页面打不开、哪篇文章有错、哪个链接失效、想要什么功能。

Discussions 适合开放讨论：选题、使用体验、没有标准答案的问题。

在 Settings → General → Features 里可以打开或关闭这两个功能。用不上就关掉，仓库首页会清爽很多。

Issue 可以加标签、指派给自己、设里程碑。文章勘误用 bug 和 documentation 两个标签就够。

新建 Issue 时可以选模板，提问的人会按格式填；讨论区可以按选题、使用体验、公告分分类，别让所有内容挤在一个列表里。

PR 和 Issue 可以关联。提交说明里写 Fixes #12，PR 合并后，第 12 个 Issue 会自动关闭。

Issue 处理完要手动点 Close issue；不确定的可以留着，加个 question 标签。别把 Issue 当聊天室，一个话题开一个。

9. 国内访问和备份

GitHub 在国内的访问速度不稳定。Pages 可以当演示站、源站、备份，不建议当国内用户的主站。

国内用户为主，可以这样放：

• 主站：国内对象存储加 CDN，或者国内云主机。
• 源站：GitHub 仓库。
• 备份：本地 clone 一份，Releases 里的重要版本另存。

不要把 GitHub 当图片 CDN。raw 链接有速率限制，国内访问也慢，图片多了很容易挂。

备份不用太复杂。每隔一段时间，在本地执行：

git clone https://github.com/你的用户名/你的仓库.git

用 GitHub Desktop 的话，点 File → Clone repository，选仓库，选本地目录就行。

重要版本的压缩包，在 Releases 里也留一份。Issues 里如果有重要的反馈，定期导出或截图保存。仓库公开不等于版权放弃，私有仓库也要留本地备份。

10. 常见问题

Pages 打开是 404。 看仓库根目录有没有 index.html，文件名大小写对不对，再看 Settings → Pages 的分支和目录有没有选对。刚开启 Pages 要等一两分钟，构建失败可以到 Actions 里看日志。

私有仓库能开 Pages 吗？ 免费账号通常不行，公开仓库可以。私有仓库发布 Pages 需要对应的付费套餐。

PR 显示 There isn’t anything to compare。 说明两条分支没有差异，或者 compare 选错了分支。确认改动已经提交到 compare 分支上。

PR 显示冲突怎么办？ 在本地把 main 的最新改动合进分支，解决冲突后再提交；网页上也可以点 Resolve conflicts，改完标记为已解决。

PR 的合并按钮是灰的。 看是不是 Draft 状态、检查没通过、需要 review，或者分支保护规则要求必须 approve。按页面提示处理。

Fork 之后怎么同步原仓库？ 在你自己的仓库首页点 Sync fork，再点 Update branch。有冲突时按提示处理。

文件太大推不上去。 单文件超过 100MB 会被拒绝。安装包放 Releases，大文件用 Git LFS，或者放对象存储。

密码或 token 提交进仓库了。 去 GitHub 的 Developer settings 撤销 token，改密码，检查登录会话。只删文件不够，历史记录里还能翻到。

两步验证手机丢了。 用当时保存的恢复码。没有恢复码，只能走 GitHub 的账号恢复流程。

自定义域名一直 pending。 检查 CNAME 有没有指向 你的用户名.github.io，根域名有没有按提示加 A 记录。域名前面套了 Cloudflare 代理，先把代理关掉。解析生效后删掉域名重新添加，再等证书签发。

Actions 发布 Pages 失败。 看 Settings → Pages 的 Source 有没有选 GitHub Actions，再看 Settings → Actions → General 的 Workflow permissions 有没有给读写权限。

11. 小结

GitHub 对站长和新手的价值，不是“看起来技术”，而是一个仓库同时解决了文件管理、改动记录、静态发布、下载分发和备份。

日常最常用的路径是：建仓库 → 改文件 → 提交 → 开分支 → 提 PR → 合并 → Pages 自动更新。

用不上 PR 就自己直接改 main；用不上 Actions 就手动传文件。先把仓库和 Pages 跑通，其他的按需要加。