peaceiris/actions-gh-pages

这是什么？

核心功能

• 01将任意静态构建输出目录发布到 GitHub Pages 分支。
• 02支持 GITHUB_TOKEN、SSH 部署密钥和个人访问令牌三种认证方式。
• 03可发布到另一个外部仓库。
• 04提供 CNAME 文件、跳过 Jekyll 处理以及排除部署文件等选项。
• 05可保留已有文件，或创建只含最新提交的孤立分支。
• 06可在 Linux、macOS 和 Windows 运行器上运行。

适用场景

• 每次推送到 main 分支后，自动发布 Hugo 或 MkDocs 文档站点。
• 在 CI 中把 Next.js 或 Nuxt 的静态导出部署到 GitHub Pages。
• 借助个人访问令牌，将私有源码仓库中的站点发布到公开仓库。
• 定时重新构建并部署生成的站点。

快速上手

1. 1

   添加工作流文件 .github/workflows/gh-pages.yml 并推送到默认分支

2. 2

   使用部署步骤发布构建输出目录

   uses: peaceiris/actions-gh-pages@v4

使用前须知

• !使用 GITHUB_TOKEN 首次部署前，需要先在仓库的 Pages 设置中选择部署分支。
• !deploy_key 选项在 Windows 运行器上不可用，需要改用其他令牌方式。

收录于专题

标签

常见问题

actions-gh-pages 是什么？

一个 GitHub Action，可在工作流中把静态站点构建产物发布到 GitHub Pages 分支。 这是一个 GitHub Action，用于把构建输出目录（如 ./public 或 ./out）的内容推送到 GitHub Pages 使用的分支，默认是 gh-pages。它适用于能生成纯静态文件的各类站点生成器，包括 Hugo、MkDocs、Gatsby、mdBook、Next.js、Nuxt 和 VuePress，只需在已有工作流的构建步骤之后加入部署步骤即可。

actions-gh-pages 可以免费使用吗？用的什么许可证？

actions-gh-pages 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

actions-gh-pages 还在维护吗？

活跃维护中。actions-gh-pages 最近一次提交是在 2026年11月6日。

actions-gh-pages 适合用来做什么？

每次推送到 main 分支后，自动发布 Hugo 或 MkDocs 文档站点。 在 CI 中把 Next.js 或 Nuxt 的静态导出部署到 GitHub Pages。 借助个人访问令牌，将私有源码仓库中的站点发布到公开仓库。 定时重新构建并部署生成的站点。

actions-gh-pages 怎么安装和运行？

添加工作流文件 .github/workflows/gh-pages.yml 并推送到默认分支 使用部署步骤发布构建输出目录: uses: peaceiris/actions-gh-pages@v4

在哪里获取 actions-gh-pages？

源代码和安装说明在 GitHub 上：https://github.com/peaceiris/actions-gh-pages