一套「Hugo + GitHub + 两分支（source/main）+ 自动部署」的完整流程，你照着做就能跑起来。
约定：
source分支：Hugo 源码main分支：Hugo 生成的静态文件（给 GitHub Pages 用）
一、准备工作
1. **安装 Hugo**hugo version
- 看你系统自己装就行，确认一下版本：
- GitHub 上建仓库
- 新建一个 repo，比如：
my-blog - 默认会有一个
main分支，先保留（后面用来放静态文件）
- 新建一个 repo，比如：
二、本地初始化 Hugo 并推到 `source` 分支
1. 克隆仓库到本地：git clone git@github.com:你的用户名/my-blog.git
cd my-blog
- 创建并切到
source分支：
git checkout -b source
- 在当前目录初始化 Hugo 项目（以
my-blog为例）：
hugo new site .
- 加主题（以 Ananke 为例）：
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
在 config.toml 里加上：
theme = "ananke"
baseURL = "https://你的用户名.github.io/"
- 随便新建一篇文章测试：
hugo new posts/hello-world.md
然后去 content/posts/hello-world.md 把 draft: true 改成 false。
- 提交到
source分支：
git add .
git commit -m "init hugo site"
git push origin source
三、让 `main` 分支只放静态文件
我们让 Hugo 的输出目录指向一个单独的目录（比如 `public/`，默认就是），再用 GitHub Actions 帮你把 `public` 的内容同步到 `main` 分支，**你本地不需要切 main 分支手动搞**。GitHub 这边需要两件事：
- GitHub Actions workflow（自动构建）
- GitHub Pages 设置（从
main分支部署）
四、创建 GitHub Actions 自动构建
> 目标：当你 push 到 `source` 分支时： > > 1. 自动拉代码 > 2. 安装 Hugo > 3. 执行 `hugo` 生成静态文件到 `public/` > 4. 把 `public/` 的内容推送到 `main` 分支 >- 在本地
source分支创建 workflow 文件夹：
mkdir -p .github/workflows
- 新建文件
.github/workflows/**<font style="color:rgb(31, 35, 40);">gh-pages</font>**.yml，内容例如：
name: GitHub Pages
on:
push:
branches:
- source # 当 source 分支有更新时触发构建
jobs:
build-deploy:
runs-on: ubuntu-20.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- name: Checkout
uses: actions/checkout@v3
with:
submodules: true
fetch-depth: 0
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: "latest"
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.HUGO_BLOG }} # 你的 GitHub token
publish_branch: main # 将构建的内容推送到 main 分支
publish_dir: ./public # public 目录是 Hugo 构建后的输出目录
- 提交这个 workflow 文件：
git add .github/workflows/gh-pages.yml
git commit -m "add github actions for hugo deploy"
git push origin source
- 这时候到 GitHub 仓库的 Actions 标签页里，应该会看到 workflow 在跑。
- 如果成功，
main分支会被自动创建/更新，里面就是纯静态文件（index.html等）。
- 如果成功，
五、配置 GitHub Pages 使用 `main` 分支
1. 进入你的 GitHub 仓库页面 → Settings 2. 左侧找到 **Pages** 3. 配置： - **Source**：选 `Deploy from a branch` - **Branch**：选 `main` 分支，目录 `/ (root)` 4. 保存GitHub 会给你一个地址，通常是：
https://你的用户名.github.io/
或https://你的用户名.github.io/仓库名/
几分钟后访问这个地址就能看到你的 Hugo 博客了。
六、之后写博客的日常操作
以后你只需要动 **source 分支**：- 确保在
source分支：
git checkout source
- 新建文章：
hugo new posts/xxx.md
改好内容，把 draft: true 改成 false。
- 本地预览（可选）：
hugo server -D
浏览器访问 http://localhost:1313 看效果。
- 提交并推送：
git add .
git commit -m "add new post"
git push origin source
- GitHub Actions 会自动执行构建和部署，把更新后的静态文件推送到
main，GitHub Pages 自动更新。
七、常见坑 & 建议
1. **baseURL 写错** - 如果你仓库名不是 `你的用户名.github.io`，而是普通仓库，例如 `my-blog`， 那 `config.toml` 里的 `baseURL` 应该是：baseURL = "https://你的用户名.github.io/my-blog/"
- main 分支手动改动会被覆盖
- 不要手动在
main分支改任何东西，因为每次 workflow 部署都会覆盖。 - 所有内容都通过
source分支的 Hugo 代码来维护。
- 不要手动在
- Actions 权限
- 一般默认的
GITHUB_TOKEN有权限推到main，不用额外设置。 - 如果报权限错误，去仓库 → Settings → Actions → General
确保Workflow permissions里勾选了：Read and write permissions
- 一般默认的