从零开始：我的 Hugo + GitHub 博客搭建踩坑记

Posted on Dec 28, 2025

今天正式把博客搭好了！

虽然中间遇到了不少“红字”报错，但解决问题的过程真的很有成就感。

六年一梦：从仰望到拥有，我的 Hugo 博客搭建全记录

前因后果：一个埋藏六年的种子

起源

那是6年前了。苦苦钻研V2Ray技术的我偶然认识了一位叫Kiri的小伙伴，他的博客非常漂亮——那是用Django搭建的，页面优雅、加载迅速。我第一眼就很喜欢，立刻燃起了“我也要有一个”的冲动。

然而现实很快给了我一盆冷水。Django需要扎实的Python基础，而我当时只是为了“翻墙”才开始接触Linux的皮毛，连像样的脚本都写不好。学习过程无比痛苦，最终只能放弃。

但我实在太喜欢那种风格了。退而求其次，我尝试用WordPress模仿一个差不多的……结果不提也罢。那真是一坨——又大又臭的一坨，臃肿、缓慢，每次打开都让我不忍直视。

随着时间流逝，这个想法只能搁置。我不得不承认，自己确实没有出类拔萃的自学能力。在复杂的配置和层出不穷的错误面前，我的热情一次次被消磨。

直到今年，我有了四位新“老师”：Grok、Gemini、ChatGPT和豆包。

为什么要写？为了对抗什么

在今日这个短视频横行的年代，想写点东西真的需要巨大的勇气。

我们习惯了只能坚持几秒的注意力和稍纵即逝的快感。有没有发现，自己正在慢慢失去表达思想的能力？有时候想写点什么，脑子里却一片空白，仿佛思考的肌肉已经萎缩。

我不想成为短视频的奴隶。哪怕写点永远不会有人看的文字，也好过一次又一次麻木地上滑——滑的不是屏幕，是自己宝贵的青春和时间。

今天的我也早已没了当年“必须用Django”的执念。几年前见过Hugo搭配Archie生成的博客，快速、极简，恰好满足我所有的需求：轻量、美观、可多端同步。

当机立断，就是她了。

可惜，几年前的我，即便是面对如此“简单”的博客也搭建不起来。毫无基础的我需要恶补巨量知识，哪怕一个小小的错误，Debug不出来就会消耗掉一整个下午。我也不可能每一步都去找大佬求助。

印象里尝试了几次，都失败了。

而今，借助强大的AI，我终于圆了那个当年未曾实现的梦。虽然很多步骤一知半解，但我会尽可能记录下来——一方面是为了记录，另一方面，复盘的过程也是对已学知识的强化。

折腾之路：站在巨人的肩膀上

初试：AI指路，破除壁垒

周五（没错，借助AI的力量，我这个小白搭博客只用了三天），我的思路还局限在“用自己的VPS搭建”上。

其实，借助GitHub Pages更简单方便——这就是知识壁垒。一个知识点如果自己去钻研，可能需要花费很多时间；但现在有了AI，这个过程被大大缩短了。

我把一个实例博客发给Gemini，它立刻分析出了搭建的步骤与基本思路：

本地安装Hugo
配置主题
利用GitHub Actions实现自动化部署
绑定自定义域名

当时我的MacBook Air里真是一穷二白，所以我分了两步来完成。

第一只拦路虎：环境安装

我在周五晚上首先尝试安装Hugo。由于GitHub国内访问受限，连接不稳定导致卡在Homebrew安装环节。三位“老师”说法不一：Gemini建议设置代理，豆包老师说修改host。考虑到我本地有稳定的代理，我选择了前者。

接着，由于我的系统一直没升级（插一句，2020年纤薄的Air是真好看，我当时大冤种买了16+1TB顶配，今天也不卡），安装Homebrew时其实就已经提示了兼容性问题，但我没管。结果后来brew install hugo的时候果然报错了。

这时候我请出了另一位大神——Grok。不得不说，这两位G姓的“老师”能力是真牛。很快，Hugo安装成功。

周六一天没什么实际进展，因为我当时弄错了方向，钻研到Hexo上去了。后来我详细比较了Hugo和Hexo的特点与主题生态，最终还是投奔了Hugo阵营。

这里按下不表。

决战钢锯岭：三天圆梦

今天（周日）就是决战时刻了。从五点半弄到八点半，现在仿佛做梦一般，不敢相信自己的眼睛。

这里又要提一下技术壁垒。今天之前，我脑子里其实都是混沌的——我只知道我大概想要什么样的博客，电脑里安装了基础工具，但具体如何实现，都是未知数。

真的就是一边问AI，一边摸索，最终才成功。

我的核心需求

使用 Hugo 静态网站生成器
源码保存在 GitHub 私有仓库（实现多端同步）
生成的网页部署到 GitHub Pages
使用 Archie 主题
拥有独立域名 wanger.cc
暗黑模式默认开启

详细步骤与遇到的“坑”

第一阶段：本地环境搭建

操作步骤：

# 1. 创建 Hugo 站点
hugo new site my-blog
cd my-blog

# 2. 初始化 Git（为后续版本控制做准备）
git init

# 3. 添加 Archie 主题（作为子模块，方便后续更新）
git submodule add https://github.com/athul/archie.git themes/archie

配置文件修改： 在 hugo.toml 中添加主题配置：

theme = "archie"

第二阶段：GitHub 仓库准备

创建两个仓库，这是实现“源码私有、页面公开”的关键：

blog-source（私有）：存放 Hugo 所有源代码（文章、配置、主题等）
Real-Wanger.github.io（公开）：存放 Hugo 生成的静态网页，用于 GitHub Pages 展示

第三阶段：认证问题（第一个坑）

问题现象：

git push -u origin main
# 报错：Password authentication is not supported for Git operations

解决方案：

在 GitHub → Settings → Developer settings → Personal access tokens 创建 Token
勾选 repo 和 workflow 权限（后者稍后需要）
使用 Token 代替密码进行认证

知识点： GitHub 从 2021 年起不再支持账号密码推送，必须使用 Token。

第四阶段：自动化部署（第二个坑）

这是最核心的一步——让 GitHub 在检测到源码更新时，自动生成网页并推送到公开仓库。

核心配置文件： .github/workflows/deploy.yml

name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # 重要：包含主题子模块
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true
      - name: Build
        run: hugo --minify
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.GH_PAT }}  # 使用之前创建的Token
          external_repository: Real-Wanger/Real-Wanger.github.io
          publish_dir: ./public
          publish_branch: main

第二个坑： Token 权限不足

问题现象：

! [remote rejected] main -> main (refusing to allow a Personal Access Token 
to create or update workflow `.github/workflows/deploy.yml` without `workflow` scope)

解决方案： 更新 Token 权限，补勾 workflow 权限。

第五阶段：自定义域名问题（第三个坑）

问题现象： 在 GitHub Pages 设置的自定义域名，每次推送新文章后就会消失。

原因分析： GitHub Actions 在部署时会清空目标仓库，然后推送新内容。由于我的源码中没有包含 CNAME 文件，导致域名配置被覆盖。

解决方案：

在本地创建 static/CNAME 文件：

mkdir -p static
echo "wanger.cc" > static/CNAME

修改 hugo.toml 中的 baseURL：

baseURL = 'https://wanger.cc/'

推送更改后，在 GitHub Pages 设置中重新绑定域名

第六阶段：暗黑模式配置

最初尝试（失败）： 在 hugo.toml 中添加：

[params]
    mode = "toggle"
    defaultTheme = "dark"

问题： Archie 主题默认跟随系统设置，defaultTheme 参数不生效。

再次尝试（失败）：

创建自定义 CSS 文件：

mkdir -p assets/css
touch assets/css/custom.css

在 custom.css 中添加：

/* 强制深色模式 */
body.dark {
    background: #1e1e1e;
    color: #ddd;
}

修改 hugo.toml：

[params]
    mode = "toggle"
    customCSS = ["css/custom.css"]

结果：毫无作用。。。

世上无难事，只要肯放弃

第七阶段：首页显示优化

问题： 首页直接显示全文，而不是文章列表

解决方案：

在 hugo.toml 中添加：

[params]
    showFullContent = false

在文章 Markdown 文件中添加摘要分隔符：

这是摘要内容，会显示在首页。

<!--more-->

这是正文内容，点开才能看到。

总结与反思

学到的技术点

GitHub Token 机制：替代传统密码认证，更安全可控
Git Submodule：优雅管理主题依赖，方便更新
GitHub Actions：自动化部署流水线，解放双手
CNAME 文件的重要性：维持自定义域名配置，避免“消失术”
浏览器缓存机制：如何诊断和清理，理解其工作原理
Hugo 主题自定义：通过覆盖模板和 CSS 实现个性化

实现的工作流（理想状态）

本地写作 Markdown
git push 到私有仓库
GitHub Actions 自动构建
静态网页自动部署到公开仓库
通过自定义域名访问

整个过程实现了：

✅ 源码私有保护（保护草稿和配置）
✅ 多端同步写作（随时随地上手）
✅ 自动化发布（专注内容，无需手动编译）
✅ 独立域名（专业形象）
✅ 暗黑模式（护眼友好）
✅ 响应式设计（全设备适配）

AI 助手的价值

这次经历让我深刻体会到 AI 作为“编程导师”的价值：

降低入门门槛：复杂概念用通俗语言解释
实时调试助手：报错信息即时分析，提供解决方案
知识壁垒破除者：将分散的知识点串联成可执行的步骤
永不疲倦的陪练：无论多基础的问题，都能耐心解答

下一步计划

添加评论系统：考虑使用 Giscus（基于 GitHub Discussions）
配置访问统计：可能使用 Google Analytics 或更轻量的方案
优化主题细节：调整配色、字体、间距等视觉元素
学习 Hugo Shortcodes：实现更丰富的内容嵌入
尝试图片优化：学习使用 Hugo 的图片处理功能
探索更多自动化：比如自动生成文章头图

最终感想：

六年前，我仰望别人的博客，觉得那是一座遥不可及的高山。

今天，我站在自己的山巅，回望来路——那些曾经让我望而却步的“天堑”，其实都是一块块可以搬动的石头。

技术本身并不神秘，神秘的是那个“敢于开始”的自己。而 AI，就像一位全知全能的向导，牵着我的手，一步步走过了那些我曾以为永远无法跨越的沟壑。

虽然过程曲折，但解决问题的过程让我对静态网站生成、Git 工作流和自动化部署有了更深入的理解。现在我的博客已经可以随时随地更新，真正的 “Write once, publish everywhere”！

更重要的是，我找回了写作的勇气——在这个注意力被无限切割的时代，为自己保留一片完整表达思想的净土。

网站已上线：https://wanger.cc
源码仓库：https://github.com/Real-Wanger/blog-source（私有）

谨以此文献给六年前那个羡慕别人的自己，和今天这个终于敢动手实现的自己。