免去打包烦恼，自动构建你的GitHub Pages｜玩转GitHub Pages三部曲（二）

news2025/8/3 2:21:29

本文讲述了如何利用 GitHub Actions 来自动构建 GitHub Pages 项目，免去繁琐的手动构建再提交过程，让你专注于写作。

大家的点赞和互动是我更文的动力 /(ㄒoㄒ)/ 所以我决定发起一项活动，到三月三十一日统计，留言次数和赞赏次数最多的人各将获得赠书一本。

点击上方“后端开发技术”，选择“设为星标” ，优质资源及时送达

GitHub Actions 自动构建

之前的文章我们已经讲过了如何利用 GitHub Pages 快速搭建一个自己的博客，并且我对现有比较热门的几个静态网站生成框架进行了对比，结论是选择 Hugo 作为技术选型。具体内容不再赘述，请自行查阅。

简单！这可能是最快速的个人博客搭建姿势！|原创

因为Hugo在发布到 GitHub之前需要自行本地编译打包，然后才能把打包好的源码 push 到远程仓库，这就显得很繁琐。于是有人问，可以不需要手动编译直接部署吗？

答案当然是有的！一切理论上可以偷懒的事情，都有程序做了，GitHub Actions 就解决了这个问题。持续集成由很多操作组成，比如抓取代码、运行测试、登录远程服务器，发布到第三方服务等等。GitHub 把这些操作就称为 Actions。

配置 Actions

1.准备工作

可以访问的 GitHub Pages
Git
本地源码
Hugo 环境

如果你阅读了之前的文章，这些准备工作已经就绪。

2.创建 sub mdules

hugo 的主题（ themes）是通过 Git 的 sub modules 拉取的，在 Git Actions 会在自动处理过程中会依赖子项目，没有 sub modules 文件会导致构建失败。这就需要我们在下载本地主题的时候是用 Git 的子 moudle 来拉取的，举个例子。

# 创建项目
hugo new site quickstart 
# 拉取主题
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
# 添加主题到 配置文件中
echo theme = \"ananke\" >> config.toml

3.创建 yml 配置文件

官方默认推荐的是 Jekyll ，内核对其作了支持，会根据分支自动构建发布的，但是如果使用其他静态化网页框架就需要自己来使用 GitHub Actions 来实现，Actions 其实就是 GitHub 的 pipeline 版本，使用只需要一个配置文件 .github/workflows/xxx.yml，GitHub Actions 会默认读取并且解析。

这里我们创建一个文件my-pipeline.yml。

4.配置 yml 文件

这里有两个地方可能需要修改：一是构建的分支 branches，默认是main，二是域名，如果自定义域名需要修改cname。（通常情况下可以直接复制此文件使用）

name: my-pipeline

on:
  push:
    tags:
      - '*'
    branches:
      - main # 制定需要构建的分支

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}

    steps:
      - name: checkout
        uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: setup hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.92.0'
          extended: true

      - name: build
        #run: hugo --minify#
        run: hugo -D

      - name: deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          # cname: xxx.com # 如果是自定义域名需要修改

保存好之后可以查看 Acitons 选项，如果配置有效的话可以看到已经正在执行的Workflow。

5.选择 Pages 自动构建分支

当完成了以上步骤的配置之后，如果操作全部正确，GitHub 对应仓库中会出现名为gh-pages的分支。此时进入https://github.com/{你的名字}/{你的仓库}/settings/pages页面，也就是仓库的Settings的Pages选项，选择部署的分支为gh-pages。

可能出现的问题：

没有 pages 功能：只有公开项目才有，私有项目不支持 gh-pages 分支不存在：没有成功触发 action，成功触发，会自动生成分支 gh-pages，并将静态资源保存在 gh-pages 上 cname 一直被重置：.github/workflows/my-pipeline.yml 最后一行没有设置好