一篇讲清 GitHub Pages 为什么能部署, 为什么会失败, 以及最新的可用边界和操作方式.

一. 前置知识

阅读本文前, 你只需要知道这几件事.

• GitHub 仓库有 public 和 private 两种可见性.
• GitHub Actions 可以在代码 push 后自动跑 CI/CD.
• 静态站点是由 HTML, CSS, JS 组成的文件集合.
• 大多数文档站工具和静态网站生成器都会先 build, 再把 build 产物发布出去.

如果我们更习惯传统 LNMP, 可以把 GitHub Pages 理解成一套 GitHub 托管的静态网站发布系统. 它省掉了自己维护 Nginx, PHP-FPM, SSL 证书和服务器磁盘的那部分工作.

二. 核心概念

GitHub Pages 本质上是把仓库里的静态文件发布成一个公开网站.

它有两种常见模式.

• 旧模式: 直接从某个分支发布.
• 新模式: 通过 GitHub Actions 自己 build, 然后把产物交给 Pages 部署.

对常见的文档站工具, 博客生成器, 静态网站生成器来说, 新模式更常见, 因为我们需要先生成站点文件, 再发布.

实践里碰到这类报错时, 问题往往不在文档内容本身, 而是在 Pages 的发布链路上.

• private repo + Free 计划, Pages 根本不能启用.
• Pages 没启用时, configure-pages 会报 Get Pages site failed.
• 同一个 workflow run 里出现两个同名 github-pages artifact, deploy-pages 会拒绝部署.

三. 原理/机制

GitHub Pages 的发布流程可以理解成 4 步.

1. 代码 push 到仓库.
2. GitHub Actions 触发 workflow.
3. build job 生成静态站点, 再上传 Pages artifact.
4. deploy job 读取 artifact, 把它发布成网站.

graph TD
    A[Push to repo] --> B[GitHub Actions trigger]
    B --> C[Install dependencies]
    C --> D[Build static site]
    D --> E[Upload Pages artifact]
    E --> F[Deploy artifact]
    F --> G[Public GitHub Pages URL]

如果把整个流程拆开看, 真正决定是否发布成功的通常不只是 build 本身, 还包括下面两层状态.

• 仓库可见性和套餐决定 Pages 能不能启用.
• artifact 和 deployment 决定这次发布能不能成功.

再往下拆, 还有一个很重要的概念, 就是 environment. GitHub Pages 的 deploy job 通常会使用 github-pages environment, 这样 GitHub 才能记录这次部署.

四. 实现/应用

下面这份配置可以看作一套适合大多数 Node.js 静态站点项目的最小工作流思路.

name: Deploy to GitHub Pages

on:
  push:
    branches: [master]
  workflow_dispatch:

env:
  PAGES_ARTIFACT_NAME: github-pages-${{ github.run_id }}-${{ github.run_attempt }}

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

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: site/package-lock.json

      - name: Install dependencies
        working-directory: site
        run: npm ci

      - name: Build
        working-directory: site
        run: npm run build

      - name: Upload GitHub Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          name: ${{ env.PAGES_ARTIFACT_NAME }}
          path: site/build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5
        with:
          artifact_name: ${{ env.PAGES_ARTIFACT_NAME }}

这里有几个地方比较值得留意.

• permissions 里必须有 pages: write 和 id-token: write.
• build 和 deploy 要用 needs 串起来.
• path 必须指向 build 后的目录, 比如项目生成出来的 dist/, build/, public/ 等目录.
• 如果你经常重跑同一个 workflow, artifact 名称最好带上 run_id 和 run_attempt, 这样可以避免同名 artifact 冲突.

如果仓库还是 private, 且账号是 Free, 那么即使 workflow 写对了, 也还是没法真正启用 Pages.

五. 常见误区

1. 以为 build 通过就等于 Pages 成功

这两件事其实不能直接画等号. build 通过, 只说明站点构建成功, 不代表 Pages 已经部署成功.

2. 以为 private repo 也能免费 Pages

这点比较容易误判. 根据 GitHub 官方规则, public repo 的 Free 计划可以用 Pages, private repo 需要 Pro, Team, Enterprise Cloud, 或 Enterprise Server.

3. 以为红色 run 说明站点坏了

很多时候未必如此. 有时只是旧的部署失败, 最新绿色 run 才更能代表当前站点状态.

4. 以为 rerun failed jobs 最稳

很多情况下也不见得. 像 Multiple artifacts named "github-pages" 这类问题, 往往就是同一个 run 里重复产物导致的. 遇到这种情况时, 直接跑一个全新的 workflow run 通常更省事.

六. 实战场景

下面这个案例就很有代表性.

• 仓库原来是 private, Free 计划下 Pages 无法启用.
• 改成 public 后, 终于能在 Settings -> Pages 里选择 GitHub Actions.
• workflow 里先出现 configure-pages 相关报错, 说明 Pages 站点还没准备好.
• 后来去掉不必要步骤, 保留 build -> upload-pages-artifact -> deploy-pages, 最终成功.

对传统 LNMP 用户来说, 这个流程可以类比成.

• npm run build 就像本地生成 public/ 或 dist/.
• upload-pages-artifact 就像把静态文件打包上传.
• deploy-pages 就像把打包结果切到线上发布目录.

如果后面还要给别的文档站部署 Pages, 这套思路基本都可以直接复用.

七. 最新规则和政策要点

结合 GitHub 官方文档, 下面这些规则值得特别留意.

• GitHub Pages 在 public repo 的 Free 计划可用.
• GitHub Pages 在 private repo 通常需要付费方案.
• custom workflow 是官方支持的 Pages 发布方式.
• workflow run, artifacts, logs 都可以被删除, 前提是有仓库写权限.
• Pages 更适合文档站, 博客, 官网这类静态内容, 不适合敏感交易, 也不适合直接拿来做商业 SaaS 托管.

八. 总结要点

• GitHub Pages 是静态站点托管, 不是完整服务器.
• public/private 可见性会直接影响 Pages 能否启用.
• 文档站, 博客站, 产品官网这类静态项目通常用 GitHub Actions custom workflow 部署.
• 真正容易出错的地方不是代码, 而是 Pages 启用状态, artifact, 和 deployment 这几个环节.
• 当站点已经成功上线时, 基本就说明当前 workflow 和 Pages 配置已经跑通了.

参考资料

• https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages
• https://docs.github.com/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
• https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/deleting-a-workflow-run
• https://docs.github.com/en/actions/managing-workflow-runs/removing-workflow-artifacts