新手实战：用 GitHub Actions 自动构建并发布 Hugo 网站

手动在本地运行 hugo、上传 public 目录、再检查线上页面，很容易漏步骤。更稳的做法是：每次把代码推送到 GitHub 后，让 GitHub Actions 自动构建 Hugo 网站，再把生成结果发布到 GitHub Pages。

本文面向刚开始使用 Hugo 和 GitHub Actions 的读者。完成后，你会得到一个可复制的 .github/workflows/hugo.yaml，以后写完文章只需要 git push。

方法 1：先确认本地 Hugo 能正常构建

自动部署之前，先让本地构建通过。进入 Hugo 项目根目录：

hugo version
hugo --gc --minify

如果命令成功，项目根目录会生成 public/：

ls public

常见输出类似：

404.html
categories
index.html
posts
tags

如果本地都不能构建，先修本地错误。GitHub Actions 只是自动执行命令，不会自动修复主题、配置或 Markdown 问题。

方法 2：启用 GitHub Pages 的 Actions 发布源

在 GitHub 仓库页面执行：

打开 Settings
进入 Pages
在 Build and deployment 里把 Source 改成 GitHub Actions

这一步很重要。如果 Pages 仍然指向某个分支目录，工作流即使成功，也可能不会用 Actions 的部署结果。

准备工作

先确认项目已经提交到 Git 仓库，并且默认分支是 main。如果你的默认分支是 master，后面的 workflow 里也要改成 master。

git status --short
git branch --show-current

如果还没有 workflow 目录，先创建：

mkdir -p .github/workflows

实现步骤：创建 hugo.yaml

新建文件：

nano .github/workflows/hugo.yaml

写入下面这份配置：

name: Build and deploy Hugo site

on:
  push:
    branches:
      - main
  workflow_dispatch:

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

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

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.161.1
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v6

      - name: Install Hugo
        run: |
          mkdir -p "${HOME}/.local/hugo"
          curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"

      - name: Verify Hugo
        run: hugo version

      - name: Build site
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

如果你的主题没有使用 Hugo extended，可以把下载文件名里的 hugo_extended_ 改成 hugo_。多数现代主题会用 Sass，初学者建议先保留 extended 版本。

提交并触发部署

保存文件后提交：

git add .github/workflows/hugo.yaml
git commit -m "Add Hugo GitHub Pages workflow"
git push

推送后打开 GitHub 仓库的 Actions 页面，应该能看到 Build and deploy Hugo site 正在运行。

验证结果

工作流成功后，进入部署记录，查看 Deploy to GitHub Pages 步骤输出的网站地址。

也可以在本地先检查关键文件是否存在：

test -f public/index.html && echo "index exists"

如果你使用自定义域名，再检查 static/CNAME 或 public/CNAME 是否正确生成：

find static public -name CNAME -print

常见问题排查

1. Actions 里显示 404

原因通常是 Pages 发布源没有改成 GitHub Actions，或者部署还没完成。

处理方法：

Settings -> Pages -> Source -> GitHub Actions

然后重新运行 workflow。

2. 主题文件缺失

如果主题是 Git submodule，checkout 必须包含：

with:
  submodules: recursive
  fetch-depth: 0

如果你忘了提交 submodule，先在本地检查：

git submodule status

3. baseURL 不对导致 CSS 失效

如果页面能打开但样式丢失，通常是 baseURL 不匹配。上面的 workflow 使用 GitHub Pages 输出的地址：

--baseURL "${{ steps.pages.outputs.base_url }}/"

自定义域名项目也可以在 Hugo 配置里写固定地址，例如：

baseURL: "https://www.example.com/"

4. Hugo 版本不一致

本地能构建，Actions 失败时，先比较版本：

hugo version

然后把 workflow 里的版本改成你本地正在使用的版本：

env:
  HUGO_VERSION: 0.161.1

总结

这套流程的核心很简单：本地确认 Hugo 能构建，GitHub Pages 切到 Actions 发布源，再用 workflow 构建 public/ 并部署。对初级读者来说，不需要一开始就理解所有 CI/CD 概念，先把可运行的部署链路打通最重要。以后每次新增文章，只要提交并推送，GitHub Actions 就会自动完成构建和发布。