GitHub Pages 背后的技术

十条可证伪的核心论断

先看结论。每一条都写了它服务的章节与证据强度；如果某条被推翻，对应章节的结论就要改写。证据强度标记：A 官方规范 B 一手实测 C 第三方线索，实测均为单次观测，不代表全局分位数。

先确认它到底是什么：静态托管，不是 Web 服务器

官方文档的定义很克制：「GitHub Pages 是一个静态站点托管服务，直接取用仓库里的 HTML、CSS、JavaScript 文件，可选择性地让这些文件经过一次构建过程，然后发布成网站。」注意三个动词——取用、经过构建、发布。没有"运行"，也没有"请求时处理"。

由此可以给出一条判别式，用来判断任意平台是不是同一类东西：

这条判别式能立刻解释很多现象：为什么 cache-control 敢给 600 秒（响应只随版本变化）、为什么不能有 /api/*（没有路由到函数的机制）、为什么"部署"其实是一次版本指针切换（换的是整个文件集合）。

架构换代：不是一直长这样

今天看到的 Actions 部署链路是 2022 年之后才成为主线的。GitHub 在 2022 年 7 月发布自定义 Actions 工作流 beta，同年 8 月 Actions 成为 Pages 构建与部署的默认方式；2024 年 6 月 30 日彻底关停遗留的 pagesworker 架构。这一步的意义常被低估：构建能力从平台内置的一个受限 Jekyll 沙箱，迁移到了通用的 CI 运行时，才使得 Hugo、Astro、Vite、Next.js 静态导出等任意工具链成为可能。

四种容易混在一起的"发布方式"

为什么必须是这个形状：三条约束推出整个技术栈

"只发文件"不是功能没做完，而是在一个托管数千万个仓库、且仓库内容完全不可信的平台上，唯一可规模化的选择。把三条约束写清楚，前面那些工程细节就都能推出来。

双平面：写路径与读路径几乎不相交

这是理解整套系统最有用的一张图。控制面在几秒到几分钟内执行一次，结束后 CI 容器即销毁；数据面在之后的所有时间里被反复读取，两者唯一的接触面就是那个不可变的产物。

"动态"去哪了：只有三个去处

观点标注："以写延迟换读扩展性"是本报告对架构取舍的归纳，属于工程判断而非官方表述；但 max-age=600、整体替换式 artifact、1 GB 与 100 GB/月配额这些可观测事实与它一致。第 10 章列出了不能证实或存在相反解释的项。

从一次 push 到"当前版本"：部署其实是一次 API 登记

把 .github/workflows/pages.yml 当成标本逐段读，能看清控制面的全部零件。这不是某个框架的约定，而是 Pages Deployments API 的使用范式。

# .github/workflows/pages.yml（节选，行号对应仓库实际文件）
10  permissions:
11    contents: read      # 读源码
12    pages: write        # ① 允许 GITHUB_TOKEN 创建 Pages deployment
13    id-token: write     # ② 允许请求 OIDC JWT
16  concurrency:
17    group: pages
18    cancel-in-progress: false   # 不打断进行中的部署，避免站点短暂空档
29  - run: npm ci
30  - run: npm test
31  - run: npm run typecheck
32  - run: npm run build
35-39  # 组装 site/：index.html + 同名下载副本 + .nojekyll + build.txt
40  - uses: actions/configure-pages@v5
41  - uses: actions/upload-pages-artifact@v3   # 打包上传
45-53  # 独立 deploy job：needs: build + actions/deploy-pages@v4

关键在第 41 与第 53 行：upload-pages-artifact 并不"发布"，它只是把目录打包成一个 Actions artifact；真正改变线上状态的是 deploy-pages 调用 POST /repos/{owner}/{repo}/pages/deployments。构建与部署被拆成两个 job，用 needs: build 串起来， artifact 是两者之间唯一的交接物。

artifact 是一份有严格契约的压缩包

官方对 upload-pages-artifact 的约束写得非常具体，这些约束的存在本身就在说明服务端要做什么：它必须能安全解压一个来自不可信仓库的文件包。

OIDC：为什么必须同时给两个权限

这是整条链路里最容易被当作"照抄配置"的地方。actions/deploy-pages 的官方 README 给了机制解释：

换句话说：只给 pages: write，API 知道"有人想部署"却无法可靠判断"来自哪个分支、是否绕过保护"；只给 id-token: write，连创建 deployment 的资格都没有。两者分立不是冗余，而是把"能调用"与"能证明来源"拆开。

API 请求体与确定性

成功返回 200，另有 400 / 404 / 422（校验失败或请求过频）。来源：REST API · Pages、actions/deploy-pages README、actions/upload-pages-artifact README　A 官方规范

一次 GET 的完整旅程：响应头把每一层都暴露了

控制面结束后，CI 容器已经消失。剩下的所有时间里，系统只需要回答一个问题：把某个 URL 映射成某个文件的字节。以下是 2026-11-06 对 wangjunjian.com/kof-3d/ 的真实请求路径。

把响应头当成分层探针

静态托管的好处是：链路上的每一层都会诚实地留下自己的名字。下面全部是本次实测抓到的原值，可用第 10 章的命令复跑。

接入层：DNS、Anycast 与 TLS

把这些拼起来，数据面的全部"智慧"只有两处：按 Host 与路径首段定位到某个站点的文件集合，以及在这堆文件里做目录查找。没有模板引擎、没有路由表、没有数据库查询。第 06 章会把这套查找规则用实测逐条验出来。

三层缓存、一个可解码的 ETag，以及"部署后没更新"的真相

静态托管的性能几乎全部来自缓存，而它的一致性成本也全部来自缓存。把三层拆开，很多"玄学问题"就变成可以计算的窗口。

把 ETag 逐字节拆开

本次响应的 ETag 是 "6aed7e66-c3c92"。它看起来像内容哈希，其实不是。用一行 Python 就能反推：

python3 -c "print(int('6aed7e66',16), int('c3c92',16))"
# 1793949286  801938
# 1793949286 → 2026-11-06T07:14:46+00:00  == last-modified
# 801938                                    == content-length（未压缩字节数）

即格式为 "<mtime 十六进制>-<文件字节数十六进制>"，与 last-modified 及 content-length 三者完全自洽。这个结论有明确的工程含义：

条件请求实测：带 If-None-Match: "6aed7e66-c3c92" 再请求，返回 HTTP/2 304、无响应体，仅保留 cache-control 与 etag。这就是 801938 字节的页面在回访时几乎不耗带宽的原因。B 一手实测

一致性是"有界陈旧"，不是"瞬时生效"

把发布后的可见性拆成四段：CI 构建 → API 登记版本 → 边缘节点拿到新版本 → 浏览器私有缓存过期。任何一段没走完，用户都可能看到旧页。由此得到三条可操作规则：HTML 保持短 TTL（平台已固定 600 秒）、静态资源用内容哈希文件名做长缓存、发布验证不要只看 Actions 绿灯，还要用 curl -I 看 etag / last-modified 是否变化，必要时用无痕窗口或带随机查询串排除浏览器缓存。

反证据与边界：本次没有做跨地域、跨节点的传播延迟测量，因此"部署后最长多久生效"只有一个理论窗口，没有实测分布；第 10 章把它列为待验证项。部分二手资料称 Pages 对带哈希资源给一年长缓存，本次未在官方规范中找到对应表述，故不采信。

URL 到文件是纯目录映射：SPA 深链 404 的根因

平台没有 rewrite 规则，也没有前端控制器。请求路径被当作文件系统路径处理，加上少量规范化。这一章的结论全部来自一组可复跑的 curl。

那个 9379 字节的 404 页标题是 Page not found · GitHub Pages，来自平台而不是仓库——因为本项目的 site/ 里没有 404.html。这恰好演示了回退规则：有自定义 404.html 就返回它，没有则返回平台默认页，但 HTTP 状态码始终是 404。

SPA 深链为什么必然 404，以及三种解法

客户端路由器（History API）产生的 /orders/42 在服务器上并不存在对应文件。Pages 不会把它重写到 index.html，于是直接落到 404 分支。三种解法各自有代价：

另外别忘了 base：项目站点挂在 /<repo>/ 下，绝对路径资源会指向域名根。Vite 需设 base: '/<repo>/'，或像本仓库那样用 base: './' 相对路径并把 JS/CSS 全部内联，从根上消除路径依赖。

一个 IP 托管无数站点：Host 加路径首段的二级路由

同一组 Anycast IP 后面是数千万个站点，源站如何知道该取谁的文件？答案是两级：Host 头定位账号/站点，URL 路径首段定位仓库。官方文档把站点分成用户/组织站点（仓库名必须是 <owner>.github.io，挂在域名根）与项目站点（挂在该仓库同名的子路径下），每个账号只能有一个用户站点，每个仓库只能有一个项目站点。

官方原文说得很直白：如果用户站点设置了自定义域，该账号下所有项目站点默认都会使用同一个自定义域，除非给单个仓库单独指定。这正是本次实测的 301 来源：

curl -sSI https://wang-junjian.github.io/kof-3d/
HTTP/2 301
location: https://wangjunjian.com/kof-3d/
server: GitHub.com
age: 1537 · x-cache: HIT

# 连不存在的深链也先 301，说明域名规范化发生在文件查找之前
curl -sSI https://wang-junjian.github.io/kof-3d/does-not-exist
HTTP/2 301 → https://wangjunjian.com/kof-3d/does-not-exist
# 到自定义域上才真正判 404

边界不在代码执行，而在身份与域名

因为服务器上根本不跑用户代码，Pages 天然免疫一整类服务端漏洞（命令注入、模板注入、反序列化）。代价是安全重心整体转移到另外三处。

一、公开性是默认值

官方在发布源文档里用 Warning 强调：即使仓库是私有的，Pages 站点依然对全网公开。叠加实测的 access-control-allow-origin: *，可以推出两条硬规则：产物里不能有任何秘密；前端 JS 里写死的 API key 等于已泄露。需要鉴权的场景只能把后端放到别处，且要自己处理 CORS。

二、部署身份由 OIDC 与环境规则把关

第 03 章的 OIDC JWT 含 ref claim，服务端解码后校验工作流是否来自允许的分支；官方还建议给 github-pages 环境加部署保护规则，只允许默认分支部署。这构成"谁能改线上版本"的完整链条：pages: write（授权）→ OIDC ref claim（来源证明）→ 环境保护规则（策略）→ pages_build_version（版本与 commit 绑定，可审计可回滚）。

三、悬空 DNS 与子域接管

这是 Pages 相关最常见、也最容易被忽略的真实漏洞。OWASP WSTG-CONF-10 描述的模式是：某个子域的 DNS 记录仍指向 Pages，但对应站点已被删除或禁用；由于平台按 Host 认领域名，攻击者可以在自己的仓库里配置同一域名把内容"接管"过去。检测指纹之一正是页面里的 There isn't a GitHub Pages site here.。接管后浏览器把这个子域当作你的站点：作用域为父域的 Cookie、*.example.com 的 CORS 与 CSP 允许列表、OAuth 回调白名单都会连带失守。

四、使用条款也是边界

官方限制页明确：Pages 不得用作在线业务、电商网站或以促成商业交易 / 提供 SaaS 为主的免费托管，也不应用于传递密码、信用卡号等敏感事务。这不是技术限制，而是产品定位——它解释了这个平台为什么长期保持极简，也解释了什么时候必须迁移。A 官方规范

来源：OWASP WSTG-CONF-10、About custom domains and GitHub Pages、GitHub Pages 限制

为什么能免费，以及什么时候该走

把配额表和第 02 章的约束并排看，会发现它们不是"抠门"，而是同一套设计的边界条件：写路径被限量、产物被限体积、读路径被软限流量，换来的是不需要为每个站点常驻进程。

全部取自 官方限制页　A 官方规范

和其他静态平台比，差的是"能力"不是"速度"

下表只列结构性差异。具体的免费额度、构建分钟数、计费模型变化很快，第三方汇总仅作线索，决策前请以各家官方 limits 页为准。

C 第三方线索 结构性对比参考 2026 年多篇平台横评；表中不含任何可能过期的具体数字。

迁移信号：开始需要自定义响应头、需要 PR 预览、需要服务端鉴权、产物逼近 1 GB、或流量接近软限时，就该换平台了。这些都不是"Pages 变差了"，而是需求越过了第 01 章那条判别式。

每条数据怎么来的，以及哪些结论其实还不确定

证据口径

所有 B 级数据都是单次观测，来自单一客户端与 fra 边缘区域；它们证明"存在这种行为"，不证明分位数或全局一致性。建模值（如压缩比 3.79 倍）与实测值在本章分开列出。

可复跑命令集

# 1. 响应头全貌（分层探针）
curl -sSD - -o /dev/null https://wangjunjian.com/kof-3d/

# 2. 连续两次请求，看 age 递增与 x-cache 命中
for i in 1 2; do curl -sSI https://wangjunjian.com/kof-3d/ | grep -Ei 'age:|x-cache:|x-timer:'; done

# 3. 条件请求 → 304
curl -sSD - -o /dev/null -H 'If-None-Match: "6aed7e66-c3c92"' https://wangjunjian.com/kof-3d/

# 4. ETag 解码：mtime 与文件字节数
python3 -c "import datetime; t=int('6aed7e66',16); s=int('c3c92',16); print(s, datetime.datetime.fromtimestamp(t, datetime.timezone.utc).isoformat())"

# 5. DNS：四个官方 Anycast 地址
dig +noall +answer wang-junjian.github.io

# 6. TLS 证书签发者与有效期
echo | openssl s_client -connect wangjunjian.com:443 -servername wangjunjian.com 2>/dev/null | openssl x509 -noout -issuer -subject -dates

# 7. 压缩协商
curl -sSD - -o /dev/null -H 'Accept-Encoding: gzip, br' https://wangjunjian.com/kof-3d/

# 8. URL 映射规则（注意基准域名不要重复拼路径）
for p in /kof-3d /kof-3d/ /kof-3d/index.html /kof-3d/build.txt /kof-3d/NO-SUCH.js /kof-3d/KOF-3D.html; do
  printf '%-30s ' "$p"; curl -sS -o /dev/null -w '%{http_code} %{size_download}\n' "https://wangjunjian.com$p"
done

# 9. 账号级自定义域导致的 301
curl -sSI https://wang-junjian.github.io/kof-3d/

数量级自洽性反推

反证据、被推翻的说法与待验证项

检查清单、排障表与一份最小可用工作流

发布前检查清单

排障：先按信号定位层，再改东西

反模式速查

最小可用工作流骨架

name: Deploy to Pages
on:
  push: { branches: [main] }
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: false
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: npm }
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with: { path: dist }
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

骨架与 .github/workflows/pages.yml 的差别：本项目额外加了单测、类型检查、单文件组装与 build.txt 版本标记，并在站点目录放了 .nojekyll 作防御性冗余。

成熟度阶梯

本仓库的 pages.yml 已具备 L2 与 L3 的大部分要素；最明显的剩余缺口是资源内容哈希（因采用单文件内联而不适用）与发布后的自动 etag 校验。

结论

属于共识、可直接引用的部分：GitHub Pages 是静态站点托管；2022 年后构建与部署统一走 GitHub Actions；部署通过 Pages Deployments API 登记 artifact，需要 pages: write 与 id-token: write 双权限；站点即使来自私有仓库也公开；配额为 1 GB / 100 GB 月 / 10 分钟部署超时；URL 到文件是目录映射，没有 rewrite；自定义域必须在设置或 API 中配置。

属于本报告观点、不是官方表述的部分：把系统归纳为"控制面 / 数据面双平面"；把配额与缓存陈旧统一解释为"以写延迟换读扩展性"；由 ETag 的非哈希结构推出"不可变部署必须由构建工具提供"；以及用判别式而不是框架名称来做选型判断。这些观点与全部实测数据相容，但换一种叙事也成立。

参考来源

一手 · 官方规范与 API 文档（A 级）

1. What is GitHub Pages? — 静态托管定义、用户站点与项目站点类型
2. GitHub Pages 限制 — 1 GB / 100 GB 月 / 10 分钟 / 10 次每小时及 Actions 豁免、禁止用途
3. Configuring a publishing source — 分支发布与自定义工作流、Jekyll、CNAME 文件说明、公开性警告
4. About custom domains and GitHub Pages — 站点类型、域名继承、DNS 类型、验证与接管风险
5. REST API endpoints for Pages — Create a GitHub Pages deployment 的请求体与状态码
6. actions/deploy-pages README — OIDC 机制、双权限解释、环境与超时默认值
7. actions/upload-pages-artifact README — artifact 命名、gzip 包 tar、体积与链接约束、隐藏文件默认值

一手 · 官方变更记录（A 级）

8. Custom GitHub Actions Workflows (beta)，2022-07-27 — 可自带任意构建框架
9. Sunsetting GitHub Pages' legacy worker，2024-07-08 — 2022-08 起 Actions 成为默认、2024-06-30 关停遗留架构
10. OWASP WSTG-CONF-10 · Subdomain Takeover — 接管原理、GitHub Pages 检测指纹、验证与修复顺序

一手 · 本地实证材料（B 级）

11. .github/workflows/pages.yml、vite.config.ts、scripts/inline.mjs、.gitignore、README.md（工作区 kof-3d）
12. 2026-11-06 线上站点 curl / dig / openssl 原始观测，命令见第 10 章

第三方 · 仅作线索，未采信其数据（C 级）：Fastly/Varnish 分层解读、静态托管平台横评、部署缓存问题讨论。凡涉及具体 TTL、额度与内部实现，本报告一律以官方文档或本次实测为准。