GitHub 免费部署静态博客之自动部署

前言

使用 Hugo + Mana 主题做静态网站博客，上传到公网，无需服务器搭建自己的博客，方便无论何时何地只要有网就能更新。

主要原理：GitHub 新建一个私有仓库存放源码，利用 Actions 自动构建静态网站，推送 public 文件夹到公有仓库。众所周知，本地 push 静态网站到任意公共服务器，别人就能浏览我们的网站。但前提是静态网站如何生成？我们暂且不考虑如何搭建静态网站，因为构建静态网站的工具太多了，不用工具手搓 .html 文件也行。所以这里主要是记录我自己的搭建过程。

参考视频： B站教程

参考文章： 使用 GitHub Actions 部署 Hugo 博客

1. 准备工作

• 已安装 Git（用于推送到 GitHub 仓库）
• Hugo 静态网站项目（需设置为公有仓库域名或自定义域名）

2. 部署步骤

2.1 创建私有仓库

命名为 hugo-site（或任意名称）。

git add .
git commit -m "初始提交"
git push

推送整个源代码到私有仓库。

推送完成后，私有仓库显示源代码项目。

2.2 创建公有仓库

命名为 hugo-public。

2.3 创建 Token

点击头像 → Settings → Developer Settings → Personal access tokens → Tokens (classic) → Generate new token (classic)

• Note 命名：hugo-auto-deploy
• 勾选 repo 权限
• 点击 Generate token

⚠️ 重点：保存 token 字符串！它只会显示一次。

2.4 私有仓库创建 Token 变量

回到私有仓库 hugo-site → Settings → Secrets and variables → Actions → New repository secret

• Name: HUGO_TOKEN
• Value: 粘贴刚才保存的 token

到此，已设置：

默认 Hugo 静态网站域名已设置为 https://{GitHub用户名}.github.io/hugo-public/

3. 设置 Actions

目的：每次 push 到私有仓库，都自动构建生成 public 文件夹并推送到公有仓库。

在 Hugo 项目内新建文件 .github/workflows/hugo_deploy.yaml：

name: deploy

# 代码提交到 main 分支时触发 GitHub Action
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "0.139.2"
          extended: true

      - name: Build Web
        run: hugo -D

      - name: Deploy Web
        uses: peaceiris/actions-gh-pages@v4
        with:
          PERSONAL_TOKEN: ${{ secrets.HUGO_TOKEN }}
          EXTERNAL_REPOSITORY: 你的用户名/你的公有仓库名
          PUBLISH_BRANCH: main
          PUBLISH_DIR: ./public
          commit_message: auto deploy

只需修改底部两行：

• EXTERNAL_REPOSITORY：改为你的用户名和公有仓库名
• secrets. 后的变量名：改为你设置的名称（如 HUGO_TOKEN）

然后重新 push 到私有仓库。

验证是否成功

方法一： 查看私有仓库的 Actions 标签页，显示绿色勾即成功。

方法二： 刷新公有仓库，查看是否有文件被推送过来。

4. 创建 Pages

在公有仓库 hugo-public 中启用 GitHub Pages：

• Source: Deploy from a branch
• Branch: main → / (root)

设置完成后，页面会显示：

Your site live at https://{你的用户名}.github.io/hugo-public/

打开这个网址，就能浏览你的博客了！

5. 自定义域名（可选）

如果你想绑定自己的域名：

1. 在 Pages 设置页的 Custom domain 输入你的域名 → Save
2. 在你的域名 DNS 管理后台添加解析记录：

GitHub 会自动申请 HTTPS 证书，等待几分钟即可生效。

6. 总结与注意事项

1. 域名设置：项目需要提前设置好 baseURL 为公有仓库网址（或自定义域名）
2. Token 保存：Token 只显示一次，务必复制保存；如果丢失可以重新生成
3. Action 更新：YAML 文件配置可能会随官方更新而变更，留意 GitHub 官方提醒并及时修改
4. 触发分支：确保 YAML 中的分支名（branches）与你的仓库默认分支一致（main 或 master）