Pages 与静态站

GitHub Pages 免费托管静态网站：HTML、Jekyll、或 CI 构建后的 dist/。适合文档站、个人博客、课程 demo。本课对应 git-github 路线图 的 deploying-static-websites、custom-domains、SSG。

仓库基础见 ghg-repo；用 Actions 构建见 github-actions-essentials 部署课。

学习目标

• 从分支或 Actions artifact 发布 Pages
• 配置自定义域名与 HTTPS
• 了解 SSG（VitePress、Next static export 等）部署模式

发布方式

来源	适用
main / docs/ 文件夹	纯静态 HTML、Jekyll
gh-pages 分支	传统 Jekyll 或构建输出
GitHub Actions	Vite / Next / Hugo 等 SSG

Settings → Pages → Build and deployment 选 Source。

分支目录示例

仓库结构：

docs/
  index.html
  style.css

Settings 选 Deploy from branch：main / /docs。

访问：https://<user>.github.io/<repo>/

用户/组织站特殊规则：<user>.github.io 仓库的 main 根目录即站点根。

Actions 构建 SSG

.github/workflows/pages.yml：

name: Deploy Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci && npm run build
      - 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

npm run build 输出目录按框架调整（Next 可能是 out）。

自定义域名

1. 仓库 Settings → Pages → Custom domain 填 docs.example.com
2. DNS 添加 CNAME 或 A 记录（GitHub 文档有当前 IP 列表）
3. 勾选 Enforce HTTPS（证书自动签发）

根域名 @ 常用 ALIAS/ANAME 或 A 记录；子域名用 CNAME 更简单。

SSG 选型提示

工具	特点
VitePress / Docusaurus	文档站，与 Markdown 课程契合
Next.js static export	与 platform 技术栈一致
plain HTML	零构建，适合 ghg-practice 最小 demo

练习

• 用 docs/index.html 发布 Hello Pages
• 或配 Actions 把 Vite dist 部署到 Pages
• 在 git-github 路线图 标记 Pages 节点完成

小结

Pages = 静态文件 + 可选 CI 构建 + 免费 HTTPS。 下一课综合练习：fork 开源仓提 PR 并配 CI。