Hugo 博客自动化部署指南

Aria2026-01-17约 4 分钟

警告

本文最后更新于 2026-01-17，文中内容可能已过时。

默认已完成站点搭建，如尚未搭建详见《Hugo + FixIt 博客搭建指南》。

Hugo 博客的自动化部署，本质上就是：写完内容提交代码，剩下的事情交给部署平台去做。

下面介绍自动化部署的配置方法，以及 GitHub Pages、Cloudflare Pages 的具体设置步骤。¹

创建 GitHub 仓库

打开 GitHub，点击右上角 + > New Repository，创建远程仓库：

Repository name：<username>.github.io 或自定义名称（如 blog）。
Configuration：保持默认设置 → 点击 Create Repository。

如果部署在 GitHub Pages ，建议仓库名称设置为 <username>.github.io。

配置 SSH 密钥

运行以下命令，生成 SHH 密钥对，以实现本地环境与 GitHub 之间的安全通信：

Bash
1
2
ssh-keygen -t ed25519 -C "你的邮箱地址"
cat ~/.ssh/id_ed25519.pub

生成密钥时可保持默认保存路径，如无特殊需求，设置密码（passphrase）步骤可直接回车跳过。

返回 GitHub，点击右上角头像 > Settings > SSH and GPG keys，创建 New SSH key：

Title：如 Hugo Deployment Key。
Key：复制并粘贴公钥内容 → 点击 Add SSH Key。

运行以下命令，测试 SSH 连接是否成功：

Bash
1
ssh -T git@github.com

如果输出包含 You've successfully authenticated 等提示信息，说明 SSH 配置成功。

初始化并推送

运行以下命令，创建 .gitignore，以忽略 Hugo 构建产物及本地生成的临时文件：

Bash
1
2
3
4
5
6
cat > .gitignore <<EOL
/public
/resources/_gen
.hugo_build.lock
.DS_Store
EOL

运行以下命令，初始化 Git 仓库并推送至远程仓库（记得替换 <username> 和 <repository>）：

Bash
1
2
3
4
5
git add -A
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:<username>/<repository>.git
git push -u origin main

自动化部署

GitHub Pages

GitHub Pages 提供托管静态站点服务，通过 GitHub Actions 可实现自动化构建与发布，而 Workflows 用于定义 GitHub Actions 的触发条件和执行步骤，从而在代码推送后自动构建并生成静态文件。²

打开 GitHub 远程仓库，点击 Setting > Pages > Build and deploment，将 Source 设为 GitHub Actions。

运行以下命令，创建工作流文件：

Bash
1
2
mkdir -p .github/workflows
touch .github/workflows/hugo.yaml

修改工作流文件（按需调整 HUGO_VERSION 等变量）：

YAML.github/workflows/hugo.yaml
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
name: Build and deploy
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:
      DART_SASS_VERSION: 1.97.2
      GO_VERSION: 1.25.5
      HUGO_VERSION: 0.154.3
      NODE_VERSION: 24.12.0
      TZ: Europe/Oslo
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Go
        uses: actions/setup-go@v6
        with:
          go-version: ${{ env.GO_VERSION }}
          cache: false
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Create directory for user-specific executable files
        run: |
          mkdir -p "${HOME}/.local"
      - name: Install Dart Sass
        run: |
          curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
      - name: Install Hugo
        run: |
          curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          mkdir "${HOME}/.local/hugo"
          tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
      - name: Verify installations
        run: |
          echo "Dart Sass: $(sass --version)"
          echo "Go: $(go version)"
          echo "Hugo: $(hugo version)"
          echo "Node.js: $(node --version)"
      - name: Install Node.js dependencies
        run: |
          [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
      - name: Configure Git
        run: |
          git config core.quotepath false
      - name: Cache restore
        id: cache-restore
        uses: actions/cache/restore@v5
        with:
          path: ${{ runner.temp }}/hugo_cache
          key: hugo-${{ github.run_id }}
          restore-keys: hugo-
      - name: Build the site
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/" \
            --cacheDir "${{ runner.temp }}/hugo_cache"
      - name: Cache save
        id: cache-save
        uses: actions/cache/save@v5
        with:
          path: ${{ runner.temp }}/hugo_cache
          key: ${{ steps.cache-restore.outputs.cache-primary-key }}
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        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@v4

GitHub Actions 配置可能随时间发生变化，详见《Hugo 官方文档》以获取最新示例。

Cloudflare Pages

Cloudflare Pages 提供静态站点托管与持续部署服务，支持与 GitHub 集成，代码推送后自动拉取源码、执行 Hugo 构建，并部署到全球边缘节点，无需额外配置 CI 工作流。³

打开 Cloudflare，点击 Workers 和 Pages > 创建应用程序 > 开始使用 Pages > 导入现有 Git 存储库，选择前面创建的 GitHub 仓库，点击 开始设置：

框架预设：Hugo。
构建命令：hugo --gc --minify。
构建输出目录：public。
环境变量：如 HUGO_VERSION=0.154.3（与本地 Hugo 版本保持一致）→ 点击 保存并部署。

完成后，Cloudflare Pages 将自动完成构建与部署，并为站点分配一个默认的 *.pages.dev 访问域名。

如果此前已启用 GitHub Pages，建议执行以下操作：

GitHub 远程仓库：点击 Settings >Pages > Unpublish site，关闭 GitHub Pages。
本地博客目录：删除 .github/workflows 目录，避免 GitHub Actions 仍被触发。

启用页面服务

修改主题配置文件：

TOMLconfig/_default/hugo.toml
1
2
baseURL = "https://<username>.github.io/"
# 或 baseURL = " https://<your-site>.pages.dev/"

运行以下命令，提交并推送更改至 GitHub 仓库：

Bash
1
2
3
git add -A
git commit -m "自动化部署"
git push

推送后，GitHub Pages 或 Cloudflare Pages 会自动触发构建流程，构建成功后即可访问。

日常文章更新

至此，一个基于 Git + 自动化部署的静态站点已经搭建完成。

完成写作后，只需运行以下命令，部署平台会自动完成构建与发布，无需额外干预：

Bash
1
2
3
git add -A
git commit -m "更新文章"
git push

VSCode 可视化操作：

打开 源代码管理（Ctrl+Shift+G）面板，输入提交说明，点击 提交 > 同步更改，VS Code 会自动完成 git add、git commit 与 git push。

在此基础上，可进一步为站点配置 自定义域名，将访问地址从默认的 Pages 域名切换为自己的域名，使站点更加个性化，相关操作详见《Hugo 自定义域名配置指南》。

Hugo

2026-01-16

Hugo + PicList 多图床搭建实践

留言交流