Hugo 博客自动化工作流完整指南

这是一份详尽的工作流文档，记录了从零搭建 Hugo + Obsidian + GitHub Actions 自动化博客系统的完整过程，包括所有细节、注意事项和故障排除方法。

📋 目录

系统架构
仓库结构
配置步骤
工作流详解
日常使用
故障排除
注意事项
进阶优化

🏗️ 系统架构

设计理念

目标： 实现"写作 → 提交 → 自动发布"的无缝工作流。

核心原则：

内容与配置分离
环境可复现
自动化部署
本地与 CI 一致

三仓库架构

hugo-server (主仓库)
├── jesse-blog/
│   ├── content/      → obsidian-notes (子模块)
│   ├── public/       → JiashuaiXu.github.io (子模块)
│   ├── themes/
│   └── hugo.toml
└── flake.nix

obsidian-notes (内容仓库)
├── posts/
├── about/
├── archive/
└── .github/workflows/deploy.yml

JiashuaiXu.github.io (部署仓库)
└── (Hugo 生成的静态文件)

职责划分

仓库	用途	操作频率	是否需要手动操作
`hugo-server`	Hugo 配置、主题、Nix 环境	偶尔更新配置	是
`obsidian-notes`	编写内容（日常工作）	频繁提交	是
`JiashuaiXu.github.io`	托管静态网站	自动更新	否

📁 仓库结构

hugo-server (主仓库)

hugo-server/
├── .gitmodules              # ⚠️ 关键：子模块配置
├── flake.nix                # Nix 环境定义
├── deploy.sh                # 本地部署脚本
└── jesse-blog/
    ├── content/             # → obsidian-notes (子模块)
    ├── public/              # → JiashuaiXu.github.io (子模块)
    ├── themes/
    │   └── hugo-PaperMod/   # 当前使用的主题
    └── hugo.toml            # Hugo 配置文件

obsidian-notes (内容仓库)

obsidian-notes/
├── .github/workflows/
│   └── deploy.yml           # ⚠️ 自动部署工作流
├── README.md
├── posts/                   # 博客文章目录
├── about/
└── archive/

⚙️ 配置步骤

1. 创建 obsidian-notes 仓库

在 GitHub 创建空仓库：

仓库名: obsidian-notes
可见性: Public

2. 备份现有内容

cd /path/to/hugo-server
cp -r jesse-blog/content ~/hugo-content-backup

⚠️ 重要： 始终先备份，避免数据丢失！

3. 从主仓库移除 content 目录

cd /path/to/hugo-server
git rm -rf jesse-blog/content
git commit -m "Remove content directory to prepare for submodule"
git push origin main

4. 添加 obsidian-notes 作为子模块

cd /path/to/hugo-server
git submodule add https://github.com/JiashuaiXu/obsidian-notes.git jesse-blog/content

# ⚠️ 确保 .gitmodules 中有正确的配置
cat .gitmodules | grep -A 2 "jesse-blog/content"

⚠️ 关键点： .gitmodules 必须包含子模块配置，否则 GitHub Actions 会失败！

5. 迁移内容到 obsidian-notes

cd jesse-blog/content
git checkout -b main
cp -r ~/hugo-content-backup/* .
git add .
git commit -m "Initial commit: Import existing content"
git push -u origin main

6. 配置 GitHub Token

创建 Personal Access Token：

访问: https://github.com/settings/tokens
Generate new token (classic)
权限: repo + workflow
复制 token

添加 Secret：

访问: https://github.com/JiashuaiXu/obsidian-notes/settings/secrets/actions
New repository secret
Name: GH_PAT
Value: 粘贴 token

🔄 工作流详解

GitHub Actions 工作流文件

位置: obsidian-notes/.github/workflows/deploy.yml

name: Deploy Hugo Site

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          repository: JiashuaiXu/hugo-server
          token: ${{ secrets.GH_PAT }}
          submodules: recursive
          
      - uses: DeterminateSystems/nix-installer-action@main
      - uses: DeterminateSystems/magic-nix-cache-action@main
      
      - name: Build Hugo site
        run: |
          cd jesse-blog
          nix develop --command bash -c "hugo -D"
          
      - name: Deploy to GitHub Pages
        run: |
          cd jesse-blog/public
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add .
          if ! git diff --staged --quiet; then
            git commit -m "Deploy: $(date +'%Y-%m-%d %H:%M:%S')"
            git push origin main
          fi

执行流程

触发: 推送到 obsidian-notes
Checkout: 检出 hugo-server + 所有子模块
安装 Nix: 约 30 秒
设置缓存: 首次 3 分钟，后续 10 秒
编译: Hugo 生成静态文件 (20-30 秒)
部署: 推送到 GitHub Pages (5-10 秒)

总时间: 首次 ~5 分钟，后续 ~1.5 分钟

📝 日常使用

使用 Obsidian 写作

设置 Vault:

# 方式 1: 直接使用 obsidian-notes
# 在 Obsidian 中打开 /path/to/hugo-server/jesse-blog/content

# 方式 2: 创建符号链接
ln -s /path/to/hugo-server/jesse-blog/content ~/obsidian-vault/blog

创建文章:

文章需要包含 frontmatter：

---
title: "文章标题"
date: 2025-11-11T17:50:00+08:00
draft: false
tags: ["标签1", "标签2"]
categories: ["分类"]
---

# 正文

内容...

发布流程:

cd /path/to/obsidian-notes
git add posts/my-article.md
git commit -m "Add: 新文章"
git push origin main

# 等待 1-3 分钟，访问 https://JiashuaiXu.github.io/

本地预览

cd /path/to/hugo-server
nix develop
cd jesse-blog
hugo server -D

# 访问 http://localhost:1313

🐛 故障排除

问题 1: 子模块 URL 未找到

错误:

No url found for submodule path 'jesse-blog/content' in .gitmodules

解决:

cd /path/to/hugo-server
git submodule add -f https://github.com/JiashuaiXu/obsidian-notes.git jesse-blog/content
git add .gitmodules jesse-blog/content
git commit -m "Fix: Add content submodule to .gitmodules"
git push origin main

问题 2: public 子模块引用过时

错误:

remote error: upload-pack: not our ref 4a838c8...

解决:

cd /path/to/hugo-server
git fetch origin
git reset --hard origin/main

cd jesse-blog/public
git checkout main
git pull origin main

cd ../..
git add jesse-blog/public
git commit -m "Update public submodule"
git push origin main

问题 3: GitHub Actions 权限不足

错误:

remote: Permission denied to github-actions[bot]

解决:

检查 GH_PAT token 权限
确保包含 repo + workflow
重新生成并更新 Secret

问题 4: 网站没有更新

检查清单:

GitHub Actions 是否成功运行？
文章 frontmatter 中 draft: false？
文章日期不在未来？
等待 2-5 分钟（GitHub Pages 缓存）
强制刷新浏览器 (Ctrl + Shift + R)

⚠️ 注意事项

关键文件

文件	位置	重要性
`.gitmodules`	`hugo-server/`	⭐⭐⭐⭐⭐
`deploy.yml`	`obsidian-notes/.github/workflows/`	⭐⭐⭐⭐⭐
`GH_PAT`	GitHub Secret	⭐⭐⭐⭐⭐
`flake.nix`	`hugo-server/`	⭐⭐⭐⭐
`hugo.toml`	`hugo-server/jesse-blog/`	⭐⭐⭐⭐

不要做的事

❌ 不要直接在 JiashuaiXu.github.io 编辑文件 - 会被覆盖
❌ 不要在主仓库的 content/ 提交内容 - 必须在 obsidian-notes 提交
❌ 不要忘记添加 frontmatter - Hugo 不会识别
❌ 不要泄露 GH_PAT - 等同于密码

最佳实践

✅ 定期备份内容
✅ 使用有意义的 commit 消息
✅ 文章命名使用 kebab-case
✅ 检查 Actions 运行状态
✅ 本地测试后再推送

🚀 进阶优化

1. 添加评论系统 (Giscus)

使用 GitHub Discussions 作为评论：

[params.giscus]
  repo = "JiashuaiXu/JiashuaiXu.github.io"
  repoId = "YOUR_REPO_ID"
  category = "General"
  categoryId = "YOUR_CATEGORY_ID"

2. RSS Feed

已自动启用：

全站: https://JiashuaiXu.github.io/feed.xml
分类: https://JiashuaiXu.github.io/categories/技术/feed.xml

3. 优化工作流速度

使用 peaceiris/actions-hugo 替代 Nix（更快）：

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

对比:

Nix: 1.5-5 分钟（首次慢，后续快）
actions-hugo: 30 秒（始终快速）

权衡: Nix 保证环境一致性，actions-hugo 更快但可能有版本差异。

✅ 检查清单

配置完成前确认：

创建 obsidian-notes 仓库
配置 .gitmodules 包含 content 子模块
创建 .github/workflows/deploy.yml
生成 GitHub PAT
添加 GH_PAT Secret
测试工作流
验证网站更新
配置 Obsidian Vault
设置本地 Nix 环境

🎉 总结

现在你拥有了完全自动化的博客系统：

✅ 内容管理: Obsidian 或任何 Markdown 编辑器
✅ 版本控制: Git 跟踪所有更改
✅ 自动部署: 推送即发布
✅ 环境一致: Nix 保证本地和 CI 相同
✅ 分离关注点: 内容、配置、部署独立

工作流: 写作 → 提交 → 自动发布 → 完成！🚀

📚 参考资源

最后更新: 2025-11-11
文档版本: 1.0

Hugo 博客自动化工作流完整指南#

📋 目录#

🏗️ 系统架构#

设计理念#

三仓库架构#

职责划分#

📁 仓库结构#

hugo-server (主仓库)#

obsidian-notes (内容仓库)#

⚙️ 配置步骤#

1. 创建 obsidian-notes 仓库#

2. 备份现有内容#

3. 从主仓库移除 content 目录#

4. 添加 obsidian-notes 作为子模块#

5. 迁移内容到 obsidian-notes#

6. 配置 GitHub Token#

🔄 工作流详解#

GitHub Actions 工作流文件#

执行流程#

📝 日常使用#

使用 Obsidian 写作#

本地预览#

🐛 故障排除#

问题 1: 子模块 URL 未找到#

问题 2: public 子模块引用过时#

问题 3: GitHub Actions 权限不足#

问题 4: 网站没有更新#

⚠️ 注意事项#

关键文件#

不要做的事#

最佳实践#

🚀 进阶优化#

1. 添加评论系统 (Giscus)#

2. RSS Feed#

3. 优化工作流速度#

✅ 检查清单#

🎉 总结#

📚 参考资源#

Hugo 博客自动化工作流完整指南

📋 目录

🏗️ 系统架构

设计理念

三仓库架构

职责划分

📁 仓库结构

hugo-server (主仓库)

obsidian-notes (内容仓库)

⚙️ 配置步骤

1. 创建 obsidian-notes 仓库

2. 备份现有内容

3. 从主仓库移除 content 目录

4. 添加 obsidian-notes 作为子模块

5. 迁移内容到 obsidian-notes

6. 配置 GitHub Token

🔄 工作流详解

GitHub Actions 工作流文件

执行流程

📝 日常使用

使用 Obsidian 写作

本地预览

🐛 故障排除

问题 1: 子模块 URL 未找到

问题 2: public 子模块引用过时

问题 3: GitHub Actions 权限不足

问题 4: 网站没有更新

⚠️ 注意事项

关键文件

不要做的事

最佳实践

🚀 进阶优化

1. 添加评论系统 (Giscus)

2. RSS Feed

3. 优化工作流速度

✅ 检查清单

🎉 总结

📚 参考资源