使用 GitHub Pages 挂载静态网页

这篇教程适合把 Sphinx 生成的静态站点部署到 GitHub Pages,再按需接入自定义域名.

1. 准备仓库

先在 GitHub 上创建一个仓库,名称通常直接使用 用户名.github.io.如果你只是想先把站点跑起来,也可以先不绑定域名,直接使用 GitHub 提供的默认访问地址.

如果本地项目已经接好 Sphinx 构建流程,那么发布时只需要把生成后的静态文件同步到 docs/ 目录即可.本仓库的构建脚本就是这么做的:先生成文档,再把产物复制到 docs/,同时写入 .nojekyll 和 CNAME.

2. 本地构建站点

在仓库根目录执行构建命令:

./build

构建完成后,docs/ 目录会变成 GitHub Pages 的实际发布内容.这样做的好处是,仓库里保留了一个可直接部署的静态目录,GitHub Pages 只需要读取它即可.

3. 启用 GitHub Pages

进入仓库的 Settings,找到 Pages 相关设置.

如果你使用的是 docs/ 目录,通常选择从当前分支的 docs 目录发布；如果你使用的是单独的发布分支,也可以选择对应分支作为发布源.

保存后等待 GitHub 完成部署.首次部署通常需要几分钟,完成后会给出访问地址.

4. 绑定自定义域名

域名是可选项.如果你只想要一个免费的静态站点,可以直接跳过这一节.

如果要使用自己的域名,先准备好一个已经购买的域名.常见做法是把域名托管到 Cloudflare,再在 Cloudflare 里配置 DNS 解析.

常见流程如下:

  1. 在 Cloudflare 添加站点,并把域名的 NS 记录改成 Cloudflare 提供的地址.

  2. 等域名接管完成后,在 Cloudflare 的 DNS 面板里添加解析记录.

  3. 回到 GitHub 仓库,在 Pages 设置里填写自定义域名.

  4. 等 GitHub 完成校验并签发 HTTPS 证书,再开启强制 HTTPS.

添加自己的域名

如果你想让 www.你的域名.com 指向这个站点,最简单的方式是给 www 添加一条 CNAME 记录:

类型: CNAME
名称: www
目标: 用户名.github.io

如果你想让根域名 你的域名.com 直接打开网站,推荐添加 GitHub Pages 官方提供的 A 记录；如果你的 DNS 服务支持,也可以同时加上 AAAA 记录:

类型: A
名称: @
目标: 185.199.108.153

类型: A
名称: @
目标: 185.199.109.153

类型: A
名称: @
目标: 185.199.110.153

类型: A
名称: @
目标: 185.199.111.153

类型: AAAA
名称: @
目标: 2606:50c0:8000::153

类型: AAAA
名称: @
目标: 2606:50c0:8001::153

类型: AAAA
名称: @
目标: 2606:50c0:8002::153

类型: AAAA
名称: @
目标: 2606:50c0:8003::153

如果你使用 Cloudflare,建议把这些记录保持为 DNS only,不要走代理,否则 GitHub Pages 可能无法正常校验域名或签发证书.你也可以把根域名通过 CNAME Flattening 指向 用户名.github.io,这样对外仍然是根域名访问,但解析过程由 Cloudflare 处理.

5. 让 GitHub Pages 识别自定义域名

域名解析做好以后,还要让 GitHub 知道你要使用哪个域名.

做法有两种:

  1. 在仓库 Settings 的 Pages 页面直接填写 Custom domain.

  2. 在发布目录里保留一个 CNAME 文件,内容写你的域名.

本仓库的构建脚本会把根目录的 CNAME 复制到 docs/,这样发布时 GitHub Pages 可以直接读取到域名信息.你只需要把 CNAME 文件内容改成自己的域名,例如 www.你的域名.com 或 你的域名.com.

GitHub 侧的域名验证(可选)

如果你用的是组织账号,或者想让 GitHub 认领你自己拥有的域名,可以再做一次“域名验证”.这一步和 GitHub Pages 绑定自定义域名不是同一件事:前者是让 GitHub 确认你拥有这个域名,后者是让站点可以通过这个域名访问.

一般流程是:

  1. 打开组织的 Settings.

  2. 进入 Security 里的 Verified and approved domains.

  3. 点击 Add a domain,输入你要验证的域名.

  4. 按 GitHub 提示到 DNS 服务商那里添加一条 TXT 记录.注意这个txt记录要包括复制部分+你的域名!

  5. 等 DNS 生效后回到 GitHub,继续验证并完成确认.

GitHub 会给你一个专门的 TXT 记录名和值,照着填写即可.DNS 生效可能需要一点时间,官方说明里最长可能要等 72 小时.验证完成后,如果只是为了拿到 Verified 标识,TXT 记录可以按需删除.

这个流程通常用于组织主页、团队信息页或企业域名校验；如果你只是给个人仓库做 Pages 站点,通常只需要前面的 Pages 自定义域名配置.

6. 验证是否生效

部署完成后,先检查这几个点:

  1. 默认的 GitHub Pages 地址是否可以打开.

  2. 自定义域名是否已经解析到 GitHub Pages.

  3. 页面里的 CSS 和 JS 是否正常加载.

  4. HTTPS 是否已经可以开启.

如果样式或脚本加载失败,通常是静态资源路径不对,或者构建产物没有完整同步到 docs/.如果页面能打开但资源 404,优先检查构建产物和 CNAME、.nojekyll 是否都被复制到了发布目录.

7. 更新站点

以后只要修改 Sphinx 源文档,再重新执行构建并提交 docs/ 目录即可.GitHub Pages 会自动重新部署,站点内容也会随之更新.

8. 小结

最稳妥的流程就是:本地用 Sphinx 生成静态文件,把产物放进 docs/,在 GitHub Pages 里选择这个目录作为发布源；如果需要域名,再通过 Cloudflare 配置 DNS 并在 Pages 中填写自定义域名.