Plugin Actions-GH-Pages 一条命令把静态站推到代码托管平台

一、项目介绍

用静态站点生成器做站，最烦的往往不是生成，而是发布：每次改完内容，都要手动把产物传到 gh-pages 分支；或者自己写一堆 git 命令，还得处理缓存、权限、提交历史。peaceiris/actions-gh-pages 就是把这段流程收进一条 GitHub Actions 步骤。

在 workflow 里写三行，指定要发布的目录，Action 就把静态文件推送到远端 gh-pages 分支，站点随之更新。它和 Hugo、MkDocs、Gatsby、mdBook、Next、Nuxt 等各类静态站点生成器都能配合使用。

令牌选择上它支持三种：仓库内置的 github_token（私库公库都可用、HTTPS、无需任何配置）、SSH 协议的 deploy_key、以及 HTTPS 的 personal_token。对刚开始折腾 Pages 的人来说，直接用 secrets.GITHUB_TOKEN 就能跑通，不必先去设置个人访问令牌。当前版本 v4.1.0，MIT 协议。

静态站点的发布环节，看起来只该是"把文件传上去"，但真做过的人都知道它会持续制造小麻烦：手动 scp 或 rsync 到 gh-pages 分支，权限经常出错；每次全量推一遍，历史记录被冲成一坨；构建产物里有些文件不该发布却顺手带上了。这个 Action 把这些细节都收进了标准实现。

与静态站点生成器的配合是它最顺手的部分。Hugo、MkDocs、Gatsby、mdBook、Next、Nuxt 等生成器的产物目录各不相同，Action 通过 publish_dir 指定要发布的目录即可，不需要为每个生成器写一套分支操作。

三种令牌的划分对应三种真实场景。最常用的是 github_token：Actions runner 会自动注入一个 GITHUB_TOKEN 密钥，不需要任何配置就能跑通，这对新手最友好，也避免了"为了发个站点先学会创建个人访问令牌"的门槛。私有仓库需要访问其他仓库或需要长期有效凭据时，才需要 deploy_key（SSH 协议）或 personal_token（HTTPS）。

内置缓存机制是个容易被忽略的收益：只有变化的文件会被推送，构建与上传都快得多。站点内容多的时候，这个差别相当明显。

需要留意的是它与 GitHub 官方 Pages Action 的关系。官方现在默认就用 Actions 方式部署 Pages，这个第三方 Action 的价值在于与静态站点生成器的更顺滑配合，以及更丰富的令牌与缓存选项。

二、项目基本信息

三、核心优势

• 一条 YAML 步骤完成构建产物发布，替代手工传文件的重复劳动
• 兼容 Hugo、MkDocs、Gatsby、mdBook、Next、Nuxt 等主流静态站点生成器
• 支持三种认证方式：内置 GITHUB_TOKEN、SSH deploy_key、个人访问令牌
• 新手无需任何前置配置，GITHUB_TOKEN 由 Actions runner 自动注入
• 内置缓存机制，避免每次发布都全量重新上传
• 发布历史可追溯，出问题能定位到具体哪次提交引起
• 内置缓存机制，只推送变化文件，构建与上传速度都受影响较小
• 与 Hugo、MkDocs、Gatsby、mdBook、Next、Nuxt 等生成器直接配合，无需为每个生成器单独写分支逻辑
• 发布历史留在 git 仓库里，站点内容变更可追溯、可回滚
• 部署步骤写成标准 YAML，可与其他 CI 步骤自由组合

四、适用场景

适合用 GitHub Pages 托管静态站、希望把发布纳入 CI 自动化的个人与团队；也适合从本地手动上传切换到可审计的流水线发布的项目。

如果你的项目已经用官方 Pages Action 且部署顺利，没有必要换——官方方案更省心，也少一层第三方依赖。

值得用它的场景主要是：站点由多种生成器混合产出、希望用 deploy_key 走 SSH 免去 PAT 管理、或者站点文件量大到需要缓存来提速。

落地时有几个容易踩的点。第一，publish_dir 必须和生成器的实际输出目录一致，MkDocs 是 site，Hugo 常见是 public，Next 要先 next build 导出静态资源，写错就是"部署成功但页面 404"。第二，站点开启 Jekyll 主题时，Action 提供了对应的开关，需要按文档启用。第三，私有仓库使用 github_token 部署前，要确认仓库的 Pages 设置里 Source 已经选成 GitHub Actions。

对于纯静态站、个人博客这类场景，这个 Action 的配置量很小，一份 workflow 文件加三行就能跑起来。

如果你正被同类问题反复绊住——要么是人肉重复劳动没完，要么是工具装不上跑不通、要么是产出的结果根本没法用——那这个项目值得先花十分钟装一遍试试。

五、安装教程

当前最新版本 v4.1.0。下面是可直接执行的安装方式：

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Build site
        run: npm ci && npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

常见报错与处理：依赖缺失时先确认运行时版本（Node、Python、Rust、PHP 等）是否满足项目要求；网络超时多半是镜像或代理问题，可换源重试；权限类报错请检查当前账号是否已登录对应平台，以及脚本是否需要管理员权限执行。

六、使用示例

下面这段是可以直接参照的真实用法：

# 私有仓库需要授权访问时，改用 SSH deploy_key
- name: Deploy to gh-pages branch
  uses: peaceiris/actions-gh-pages@v4
  with:
    deploy_key: ${{ secrets.DEPLOY_KEY }}
    publish_dir: ./public
    publish_branch: gh-pages

# 需要在 GitHub 仓库 Settings -> Pages 中把 Source 设为 GitHub Actions
# （GitHub Pages 自 2022 年起默认已改用 Actions 方式）

七、常见问题

问：GITHUB_TOKEN 和个人访问令牌有什么区别？答：GITHUB_TOKEN 是 Actions runner 自动创建的临时凭据，开箱即用但权限范围受限；个人访问令牌权限更广，适合需要跨仓库或长期访问的场景。

问：私有仓库能用吗？答：可以，三种令牌都支持私有仓库，但需要相应授权：deploy_key 需要手动配置 SSH 密钥，personal_token 需要手动创建。

问：每次发布都会重传整个站点吗？答：Action 内置缓存机制，只推送变化的文件，构建速度与上传量都因此改善。

问：GitHub 官方不是已经有 Pages Action 了吗？答：是的，官方现在默认就用 Actions 方式部署 Pages；这个第三方 Action 的价值在于与静态站点生成器的配合更顺滑，以及更丰富的令牌与缓存选项。

问：部署后页面还是旧的？答：先确认 publish_dir 与生成器实际输出目录一致，再检查缓存是否命中了旧产物。

问：能让 Pages 走自定义域名吗？答：可以，域名与部署方式无关，在仓库 Settings → Pages 里配置 CNAME 与自定义域名即可。

以上是实际使用中最常被问到的几个问题。若遇到文档未覆盖的情况，可以先翻项目的 Issues 与 Discussions 区，那里有更多真实踩坑记录。

八、总结

Actions-GH-Pages 在把重复流程沉淀成可复用的能力这件事上做到了足够扎实的程度：它不追求大而全，而是把一个具体环节做透，让原本要靠人盯的流程变成可以交给工具执行的流程。

从上面的安装步骤和使用示例可以看出，它的接入成本并不高：一条命令装好，按提示完成配置，然后就能把它放进你原有的工作流里。如果你正在被同类问题困扰，不妨先在自己的一小块任务上试一轮，确认顺手了再推广到日常流程中。