使用Hugo和GitHub Pages搭建个人博客

本片文章主要记录自己使用 Hugo 搭建个人博客，并通过 GitHub Actions 将其自动发布到 GitHub Pages 上。

概述

Hugo 是一个使用 Go 语言编写的静态网站生成器 (Static Site Generator，SSG)。它的主要作用是将基于 Markdown 的内容转换为完整的、可部署的 HTML 静态网站。它以速度快、易于使用、可扩展性强而著称，广泛应用于博客、文档站、公司官网等场景。

GitHub Pages 是 GitHub 提供的一个免费静态网站托管服务，你可以将 HTML/CSS/JS（或者使用 Hugo、Jekyll、VuePress 等静态网站生成器构建的站点）部署到 GitHub 上并通过一个 GitHub 提供的域名（如 https://yourname.github.com）访问。

GitHub Actions 是 GitHub 提供的一套持续集成/持续部署（CI/CD）平台，可以让你在 GitHub 仓库的生命周期中自动执行各种任务，比如编译构建、测试、部署等。

准备

GitHub 上准备两个仓库，一个用来存放 markdown 原始文件，另外一个 GitHub Pages 仓库用来存放使用 Hugo 生成的静态文件。

blog: 私有仓库，用来存放原始文件。
holixsure.github.io: GitHub Pages 固定命名的仓库，用来存放博客静态文件，使用 Hugo 生成的静态文件将推送到这个仓库中。

如果需要通过域名访问，还需要注册一个域名，然后将域名解析指向 Github Pages 地址。

Hugo 安装和使用参考 Hugo 官方文档 (中文文档)

使用 Hugo 创建静态博客

创建博客目录

使用 hugo 命令创建博客根目录

$ hugo new blog

关联 GitHub 仓库

将创建的根目录与存放原始文件的仓库关联起来，后续新增或修改的文件就可以推送到 GitHub 上。

$ cd blog
$ git init
$ git remote add origin git@github.com:holixsure/blog.git

关联主题仓库

在 Hugo 官方主题中选择自己喜欢的主题，将对应的仓库 git clone 到 themes 目录中，我这里选择将主题仓库 fork 到自己的仓库中，这样可以对主题做一些修改，避免与原主题产生冲突。

$ git submodule add git@github.com:holixsure/linen.git themes/linen
$ echo "theme = 'linen' >> huto.toml"

使用此主题需要将主题目录下的 package.json 和 package-lock.json 拷贝到博客根目录下，执行 npm install 命令

$ npm install

创建页面

在 content/posts 目录下创建 markdown 文件，也可以使用 hugo 命令创建。

$ hugo new content/posts/my-first-post.md

本地测试

在新建的页面文件中输入内容后可以使用以下命令查看页面。

$ hugo server --buildDrafts
$ hugo server -D

启动成功后访问 http://localhost:1313 查看页面内容。

使用 GitHub Actions 自动发布

由于我这里是将博客源文件和最终生成的静态页面在两个仓库中，将静态文件部署到另一个仓库（holixsure/holixsure.github.io），需要解决权限问题。默认的 GITHUB_TOKEN 只能操作当前仓库，无法推送到外部仓库。

推荐使用 SSH Deploy Key 的方式，这是最安全且官方推荐的做法。

第一步：准备 SSH Key

需要生成一对 SSH 密钥（公钥和私钥）：

在本地终端（Terminal/Git Bash）运行：

$ ssh-keygen -t rsa -b 4096 -C "github-actions-deploy" -f gh-pages-deploy

一路回车，不要设置密码

你会得到两个文件：
- gh-pages-deploy (私钥)
- gh-pages-deploy.pub (公钥)

第二步：配置目标仓库（接收代码的仓库）

打开 holixsure/holixsure.github.io 仓库页面。
进入 Settings -> Deploy keys。
点击 Add deploy key。
Title: 填写 Action Deploy Key (或其他你喜欢的名字)。
Key: 复制 公钥 (gh-pages-deploy.pub) 的内容粘贴进去。
重要：勾选 Allow write access (允许写入权限)。
点击 Add key。

第三步：配置源仓库（运行 Action 的仓库）

打开 holixsure/blog 仓库页面。
进入 Settings -> Secrets and variables -> Actions。
点击 New repository secret。
Name: 填写 ACTIONS_DEPLOY_KEY (必须与下面配置文件里的名字一致)。
Secret: 复制 私钥 (gh-pages-deploy) 的内容粘贴进去。
点击 Add secret。

第四步：添加 Workflow 配置文件

在博客根目录下创建 .github 目录，并新建 deploy.yaml 文件（配置文件名随意）。

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - run: npm install
      - run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: holixsure/holixsure.github.io
          publish_branch: master
          publish_dir: ./public
          user_name: "github-actions[bot]"
          user_email: "github-actions[bot]@users.noreply.github.com"
          cname: www.holixsure.com

最后将代码 push 到 github 上，会自动触发 GitHub Actions 生成静态文件并同步到另外一个仓库中。