GitHub Pages 托管静态页面

GitHub Pages 是静态网站托管方案中接入成本较低的一种：将仓库的指定分支或目录映射为 *.github.io 域名下的静态站点。它不要求额外的服务器管理，CI 也可以保持在较轻配置，HTTPS 证书由平台自动处理。

---

部署流程

1. 创建一个 Public 仓库（或 GitHub Pro 的 Private 仓库）
2. 将静态文件（HTML/CSS/JS）推送到仓库
3. Settings → Pages → 选择部署分支和目录 → Save
4. 站点在 https://<username>.github.io/<repo>/ 可用

如果仓库名命名为 <username>.github.io，站点直接部署到根域名 https://<username>.github.io/，不需要 /repo/ 前缀。

---

构建机制

GitHub Pages 默认通过 Jekyll（Ruby 静态站点生成器）构建。如果你的仓库中有 Jekyll 配置文件（_config.yml），GitHub 会自动执行 Jekyll 构建。

对于纯 HTML 或使用其他构建工具（Vite/Webpack/VuePress）的项目：

• 在仓库根目录创建空的 .nojekyll 文件可以跳过 Jekyll 处理
• 更常见的做法：在 GitHub Actions 中自定义构建流程，将构建产物推送到 gh-pages 分支，Pages 直接 serve 该分支

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

---

自定义域名与 HTTPS

GitHub Pages 支持绑定自定义域名：

1. 在域名 DNS 中添加 CNAME 记录指向 <username>.github.io
2. 在仓库 Settings → Pages → Custom domain 中填入域名
3. 勾选 Enforce HTTPS（GitHub 自动申请 Let's Encrypt 证书）

注意：apex domain（example.com 不带 www）需要通过 A 记录指向 GitHub Pages 的 IP 地址（会变化，需查阅 GitHub 文档获取最新 IP），而不是 CNAME。

---

资源限制

限制项	数值
仓库大小	1GB（含 Git 历史）
站点大小	1GB（构建后）
带宽	100GB/月
构建次数	10 次/小时

100GB/月的带宽对个人博客和项目文档通常足够。超过限制后 GitHub 可能暂停 Pages 服务，因此在流量不稳定的场景中，通常会再接一层 CDN（如 Cloudflare）做缓存。

---

与其他平台的对比

平台	免费额度	构建工具	自定义域名	Serverless Functions
GitHub Pages	100GB带宽/月	Jekyll / Actions	✅	❌
Vercel	100GB带宽/月	自动检测框架	✅	✅（Node/Go/Python）
Netlify	100GB带宽/月	自动检测框架	✅	✅（Node/Go）
Cloudflare Pages	无限带宽	自动检测框架	✅	✅（Workers）

GitHub Pages 的优势是与 GitHub 仓库深度集成、无需额外账户。劣势是不支持 Serverless Functions、构建次数有限、且不提供 Vercel/Netlify 的 PR 预览部署功能。