使用 Hugo + GitHub Pages + PaperMod 主题 + Obsidian 搭建开发博客

目前（2026年）一套比较稳定、好用的 Hugo 博客搭建流程，特别适合用 Obsidian 写笔记/文章，然后推送到 GitHub Pages 的游戏开发/技术类博主。

参考示例仓库（可对照）： https://github.com/ZHLOVEYY/ZHLOVEYY.github.io

1. 本地环境安装（macOS + Homebrew）

复制代码

```bash
# 安装 Hugo（推荐 extended 版，支持 SCSS 等）
brew install hugo

# 新建站点
hugo new site my-game-dev-blog

cd my-game-dev-blog

# 初始化 git 仓库
git init

2. 添加 PaperMod 主题（推荐方式：submodule）

Bash

复制代码

git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# 或者更轻量的浅克隆
# git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

在配置文件中启用主题：

复制代码

# hugo.toml
theme = "PaperMod"

3. 创建第一篇测试文章

Bash

复制代码

hugo new posts/my-first-godot-tutorial.md

打开文件，修改 front matter 示例：

复制代码

---
title: "我的第一个 Godot 教程"
date: 2026-02-02T12:00:00+08:00
draft: true
description: "Godot 入门小示例"
tags: ["Godot", "游戏开发", "教程"]
categories: ["游戏引擎"]
---

4. 本地预览

复制代码

# 普通预览（不含 draft）
hugo server --minify

# 显示草稿文章（推荐开发时使用）
hugo server -D --minify

访问：http://localhost:1313

5. 图片存放与路径规范（最容易出错的地方）

图片统一放在 static/ 目录，例如：static/images/godot-node.png
Markdown 写法（推荐相对路径，从根开始）：
重要：关闭 Obsidian 的「附件重命名」「自动调整路径」等插件，避免破坏 Hugo 路径规则

6. GitHub Pages + Actions 自动部署

参考官方文档（2025--2026 推荐方式）： https://gohugo.io/hosting-and-deployment/hosting-on-github-pages/

仓库 Settings → Pages → Source 选择 GitHub Actions

在项目根目录创建文件：.github/workflows/hugo.yml

推荐配置（适用于 PaperMod + submodule）：

复制代码

name: Deploy Hugo site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive

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

      - name: Build
        run: hugo --minify

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

7. 解决线上图片 404 / 路径错误（最关键一步）

确保 hugo.toml 中 baseURL 正确：

baseURL = "https://你的用户名.github.io/" # 必须以 / 结尾
创建自定义图片渲染模板（强烈推荐）：

路径：layouts/_default/_markup/render-image.html

内容（保险写法）：

复制代码

{{- $u := urls.Parse .Destination -}}
{{- if not $u.IsAbs -}}
  <img src="{{ printf "%s%s" $.Page.Site.BaseURL .Destination | safeURL }}" 
       alt="{{ .Text }}"{{ with .Title }} title="{{ . }}"{{ end }} />
{{- else -}}
  <img src="{{ .Destination | safeURL }}" 
       alt="{{ .Text }}"{{ with .Title }} title="{{ . }}"{{ end }} />
{{- end -}}

8. Obsidian 写作推荐工作流

Vault 根目录 ≈ Hugo 项目根目录（可符号链接）
文章统一放在 content/posts/ 文件夹
关闭 Obsidian 的 Wiki 链接自动补全（[[ ]] Hugo 默认不识别）
所有图片丢进 static/images/
用 VS Code + Front Matter 插件管理 yaml 元数据（标题、标签、draft、分类等）

9. 常见问题快速定位

图片本地 ok，线上 404 → 检查 baseURL + 是否创建 render-image.html
submodule 没内容 → git submodule update --init --recursive
public/ 目录别放东西 → 它每次构建都会被清空重建
想预览草稿 → hugo server -D
Actions 构建失败 → 确认 submodules: recursive 已设置

祝搭建顺利～