Hugo + GitHub Action + Github Pages，搭建博客自动发布

2023.08.13 11:31 技术分享 hugo github action bash blog

我的方案由以下两个核心部分：

博客源仓库，对博客配置及所有文章 .md 源文件进行版本管理，配合 GitHub Action 进行自动化部署，自动生成静态站点推送到 GitHub Pages 博客发布仓库。
GitHub Pages 博客发布仓库，使用 GitHub Pages 实现网站部署，可以通过域名 CNAME 解析使用自定义域名。

使用 Hugo 搭建博客

Hugo 是用 Go 实现的博客工具，采用 Markdown 进行文章编辑，生成静态站点文件，支持丰富的主题配置，也可以通过 js 嵌入像是评论系统等插件，高度定制化。除了 Hugo 外，还有 Gatsby、Jekyll、Hexo、Ghost 等选择，实现和使用都差不多，可以根据自己的偏好进行选择。

安装 Hugo

我使用的是 macOS，所以使用官方推荐的 homebrew 方式进行 hugo 程序的安装，其他系统可参考官方文档。

brew install hugo

完成后，使用以下命令进行验证(查看版本号)：

hugo version

创建 Hugo 网站

hugo new site blog-demo

配置主题

创建我们的站点后，需要进行主题配置，Hugo 社区有很丰富的主题，可以通过官网 Themes 菜单选择自己喜欢的风格，查看预览效果，选择后可以进入主题项目仓库，一般都会有很详细的安装及配置说明。下面我就以我目前在使用的 smol 这个主题为例，演示一下配置流程。

cd blog-demo
git clone  [email protected]:colorchestra/smol.git themes/smol
cd themes/smol
rm -rf .git

初始化主题基础配置后，我们可以在 config.toml 文件中进行站点细节配置，具体配置项参考主题说明文档。

参考config.toml内容

theme = "smol"

发布新文章

hugo new posts/blog-test.md

本地调试站点

进行本地实时调试预览。

hugo server

运行服务后，我们可以通过浏览器 http://localhost:1313 地址访问我们的本地预览网页。

GITHUB PAGES 仓库

GitHub Pages 仓库建立完成后，可以在设置中配置自己注册的自定义域名来指向 GitHub Pages 生成的网址。此外，需要将博客站点配置文件 config.toml 中的 baseURL 改为自己的自定义域名。

GitHub Pages 发布博客

我们现在已经可以通过自定义域名来访问我们的 GitHub Pages 页面了，目前因为项目仓库是空的，访问后会报 404 页面。

Hugo 生成的静态网站通过 GitHub Pages 服务进行托管，因此我们需要上传 Hugo 生成的静态网页文件至 GitHub Page 项目仓库。

手动发布

hugo
cd public

Hugo 默认会将生成的静态网页文件存放在 public/ 目录下，我们可以通过将 public/ 目录初始化为 git 仓库并关联我们的 clin003/blog_html 远程仓库来推送我们的网页静态文件。

git init
git remote add origin [email protected]:baicaime/meBlog
git add .
git commit -m "debug"
git push origin main

推送到 GitHub Pages 仓库，稍等几分钟即可通过我们的自定义域名来访问我们的博客站点了，和

hugo server

本地调试完全一致。

自动发布

因为我们的博客基于 GitHub 与 GitHub Pages，可以通过官方提供的 GitHub Action 进行 CI 自动发布。 GitHub Action 是一个持续集成和持续交付(CI/CD) 平台，可用于自动执行构建、测试和部署管道，可以通过简单的配置即可直接使用。

配置在仓库目录 .github/workflows 下，以 .yml 为后缀。我的 GitHub Action 配置为 deploy.yml 自动发布示例配置如下：

name: Deploy Hugo site to Pages
on:
  push:
    branches: [ "main" ]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
defaults:
  run:
    shell: bash
env:
  NAME: BLOG_push
  # 推送目标仓库 格式 用户名/仓库名
  TARGET_REPOSITORY_NAME: baicaime/meBlog
  # 同步临时目录(可选)
  CLONE_DIR: tmp_public
  # 构建临时目录(可选)
  BUILD_DIR: tmp_build
  # 配置git用户名
  GIT_USERNAME: baicaime


jobs:
  # This workflow contains a single job called "build"
  build:    
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.117.0    
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
      - uses: actions/checkout@v3
      - name: Build with Hugo
        env:
          # For maximum backward compatibility with Hugo modules
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/" \
            -d ${{ env.BUILD_DIR }}          
      
      - name: Git Config
        run: |
          git config --global user.email "[email protected]"
          git config --global user.name "${{ env.GIT_USERNAME }}"
          echo "配置git完成"          

      - name: Git clone
        run: |
          echo "同步目标仓库(开始)"
          git clone --depth 1 https://github.com/${{ env.TARGET_REPOSITORY_NAME }}.git ${{ env.CLONE_DIR }} &> /dev/null
          echo "同步目标仓库(完成)"          

      - name: Git push
        run: |
          cp -rf ${{ env.BUILD_DIR }}/*  ${{ env.CLONE_DIR }}/
          cd ${{ env.CLONE_DIR }}
          echo "${{ github.event.head_commit.message }} `date +%FT%T%z`" > _pub_time.html         
          git add .
          git commit --message "Update ${{ env.NAME }} from ${{ env.TARGET_REPOSITORY_NAME }} ${{ github.event.head_commit.message }}"
          git push -f -q https://oauth2:${{ secrets.GIT_TOKEN }}@github.com/${{ env.TARGET_REPOSITORY_NAME }}.git main
          echo  "git push  ${{ env.TARGET_REPOSITORY_NAME }} (完成)"

on 表示 GitHub Action 触发条件，我设置了 push 和 workflow_dispatch 两个条件：

push，当这个项目仓库发生推送动作后，执行 GitHub Action
workflow_dispatch，可以在 GitHub 项目仓库的 Action 工具栏进行手动调用

jobs 表示 GitHub Action 中的任务，我们设置了一个 build 任务， runs-on 表示 GitHub Action 运行环境，我们选择了 ubuntu-latest。 build 任务包含了 Install Hugo CLI 、Checkout、Build with Hugo、Git Config、Git clone 和 Git push 六个主要步骤，其中 run 是执行的命令，uses 是 GitHub Action 中的一个插件，我们使用了 actions/checkout 这个插件。其中 Checkout 步骤中，可以在 with 中配置 submodules 值为 true 同步博客源仓库的子模块（比如主题模块，由于我们没有使用子模块方式安装hugo主题，所以不需要这个参数）。

需要将上述 deploy.yml 中：

TARGET_REPOSITORY_NAME 改为自己的 GitHub Pages 仓库，如我的设置为 baicaime/meBlog
GIT_USERNAME 改为自己 GitHub Pages 仓库的用户名

因为我们需要从博客仓库推送到外部 GitHub Pages 仓库，需要特定权限，要在 GitHub 账户下 Setting - Developer setting - Personal access tokens 下创建一个 Token。

权限需要：

Contents 	read/write

配置后复制生成的 Token（注：只会出现一次），然后在博客源仓库的

Settings - secrets and variables - Actions

中添加

GIT_TOKEN

环境变量为刚才的 Token，这样 GitHub Action 就可以获取到 Token 了。

推送测试

完成上述配置后，推送代码至仓库，即可触发 GitHub Action，自动生成博客页面并推送至 GitHub Pages 仓库。

GitHub Pages 仓库更新后，又会自动触发官方页面部署 CI，实现网站发布。

现在每当我们本地通过熟悉的 Markdown 语法完成博客内容编辑后，只需要推送代码，等待几分钟，即可通过我们的自定义域名访问更新后的网站。

以上就是我通过 Hugo 与 GitHub Action 实现的博客自动部署系统，我自己的实现仓库在 baicaime/meBlog 仓库中