2021年我写过一篇 Hugo 博客搭建教程，当时生成式 AI 还没有出现，代码还要“一句一句写”，在操作者普遍没有什么代码知识的背景下，搭建博客期间大部分问题的解决都需要依靠参考前人的经验细节来反复试错，和抽奖开盲盒也没有什么本质区别，当时写博客，我的想法就是，我已经把这件事的所有坑几乎都踩了一遍了，不如总结一下经验。

时过境迁，2022年底，ChatGPT 横空出世，如今是2026年，这几年里我有时候会想，是不是可以把 Hugo 搭建教程更新一下？又觉得，AI 发展至今，代码能力已经远远超过了彼时的想象，问一下 AI 就能完成的事情，专门写一篇文章也没什么必要，于是按下不提。

不过最近和朋友聊了一些相关内容，加上还在修博客新主题的 Bug，忽然感觉还是可以写一下这个题目，只不过重点调换一下，从具体的步骤，转向为提供一些思路和可能性，希望能有一些帮助。

以防万一的前提：本文（及本博客的所有文字内容）除明确署名为 AI 的部分之外，均由人类撰写。
文章中的链接有些鼠标悬浮（手机端点击）可以打开对应图片，欢迎探索。

一些前期准备

首先速战速决解决一些概念问题：

• 静态博客是什么：静态博客是一系列已经做好的 HTML 网页，它们可以被发布到网络上变成一个网站，你现在看到这篇文章的地方就是一个静态博客。
• 静态博客的优点：一种定居体验，它是一个完全属于你的网站，你可以决定它的样式、结构、交互、内容、域名，文章内容不需经过任何人审查，原始版本保存在本地和 GitHub，几乎没有丢失风险，只要你愿意它就可以在互联网上呆上三十年。
• Hugo 是什么：Hugo 是一个静态博客构建工具，它负责把本地博客文件夹中的各类文件生成为最终发布的网页。
• 为什么选择 Hugo：最显著的优势是 Hugo 非常非常快，我现在的博客写了五年，有160篇文章，56万字，一共329个页面，Hugo 构建只需要 built in 491 ms 。
• 除了 Hugo 还需要什么：
  • Git：可以简单理解为上传文件到 GitHub 的工具，它是一个完善的版本控制系统，可以随时找回历史文件。
  • GitHub：代码远程托管平台，用于储存博客文件，存储的位置我们叫作 repo（repository，储存库）。
  • Vercel：它可以读取私人 repo 的内容，自动完成整套博客构建流程，并发布站点。
  • AI 工具：我将介绍的是可以操作电脑文件的 AI Agent 工具，但如果不希望让 AI 直接操作电脑，也可以使用网页端聊天式 AI。
  • VS Code：代码编辑工具，虽然可以完全通过 AI 操作，但人类一点都不动手多不好意思。
  • 网络环境：现代上网必备之技能，虽然也可以用 Gitee 等替代 GitHub（没试过），但 GitHub 还是最方便的。
• 这套方案的缺点是什么：小红书可以随时用手机编辑并发布，Lofter 可以直接在网站本身的编辑器上写作，静态博客都不可以（后面我会介绍一个替代方案），大部分情况下写静态博客文章需要在电脑前完成，每次修改都需要一次推送到 GitHub →触发 Vercel 部署→网站显示修改的流程。如果你想要流畅的图片浏览体验，需要搭配一个图床服务（可以是免费的）。如果你想要一个好看的域名，需要自主购买。

OK，我们现在开始工作

重要提醒：因为我们使用的是可以直接操作电脑的 AI Agent，因此，它能够接触到的内容，不仅包括我们与它的对话，也包括文件夹的文章、图片、配置文件乃至各种账号凭证，因此，与 AI 对话时，要掌握一些基本的隐私原则：

• 只开放必要的文件夹：限制 AI 能读取的文件夹范围，不要轻易允许它读取整个用户文件夹、笔记库或云盘。
• 不要把密码和密钥发给 AI：GitHub Token、Cloudflare API Token、图床密钥、域名账号密码等，应当手动写进环境变量或平台的加密设置中，不懂可以让 AI 教学操作，不要因为觉得方便就直接发给 AI。
• 合理使用“帮我批准”功能：在操作过程中，AI 会不断申请权限，比如安装软件、读取文件夹，有些工具会提供“帮我批准”功能，让 AI 来判断是否为风险操作。不要因为申请频繁就一股脑地全部自动批准，涉及账号权限、删除等操作的时候，一定要自己看过再下手。

真正的一键建站

我使用的工具是 Workbuddy，这是腾讯出品的一个 AI Agent 办公工具，它可以直接操作读写我电脑中的文件，并具有自主规划、读写代码库、执行终端命令并自动调试的能力。我使用它只是因为“我现在用的电脑装好的恰好是它”，你可以用任何类似的工具达到目的，比如更聪明的 Codex、Claude code，等等等等。
我使用 Workbuddy 的免费版额度和自动模型（Auto Model）。

此外，由于 AI 工具的生成性，每个人从 AI 中得到的回答都是不一样的，我们在这里只参考流程。

搭建过程其实非常简单，我们先在 Hugo Theme 中选择一个心仪的主题（这里以 Blowfish 为例，因为我感觉它比较复杂，可以触碰到各种各样的情况），在合适的位置建立一个博客文件夹后告诉 Workbuddy：

我完全没有 Git、Hugo 和前端基础，想搭建一个 Hugo 博客，使用最新版的 Hugo 程序，主题使用 Blowfish，博客文件夹为：（文件夹地址），请只在文件夹内操作，并用简单的话语来解释我碰到的问题。

AI 会开始搜索并执行以下操作

1. 在电脑中安装 Git、Curl 等必备工具
2. 搜索 Blowfish 主题及主题对 Hugo 系统的安装要求
3. 根据电脑系统信息，安装最新版本的 Hugo 程序（extended 版本）
4. 创建站点，并配置主题文件
5. 启动 Hugo 预览服务器

此时点击 AI 反馈来的预览地址（一般是 http://localhost:1313 ）我们就已经可以看到站点了，在五年前这会花掉我整整一个下午和晚上，现在大概是十分钟，实在是难以想象。

中间我们可能会遇到最多的问题是网络，比如 Git、Curl 安装不上，Hugo/主题无法下载等等，一般来说 AI 会自动切换为国内镜像进行重新尝试，或者可以把 VPN 切换到全局模式，再告诉 AI 让它调整网络。其次是 Hugo 的版本问题，一般我建议装 Hugo 的 extended 版本，很多主题都需要用到它提供的特性。最后是主题安装的不同方式，考虑到日后升级，推荐使用 git submodule 方式安装主题。

站建好了，问题来了

问题1:博客内没有文章

因为我之前完全没有看过 Blowfish 的文档，对这个主题的了解为0，启动了预览服务器之后，我才发现站点内空无一物，洁白犹如新雪，我需要站点里有一些内容，这样我才好查看站点显示效果，调整到自己喜欢的样子。我根据经验，判断一般 Hugo 主题都会自带一个示例站点，于是我告诉 AI：

主题文件里有示例站点吗，把它加到这个博客里

于是 AI 搜索主题内的示例站点，检查后告诉我：

示例站点内容很丰富——1584 个 Markdown 文件，9 种语言（en/de/es/fr/it/ja/pt-br/pt-pt/zh-cn），还带一份完整的示例 config。直接全量复制会很臃肿，而且多语言内容对单一语言博客意义不大。

并弹出几种选项让我选择，比如只加中文文章、只加英文文章、完整示例站点等，我选了只加中文文章。
这时候它出现一个问题：

复制了 177 篇中文文章，但 Hugo 重建报错：docs/getting-started 用了一个主题里没有的 shortcode theme-switcher。这是因为 exampleSite 有自己的 layouts/（含自定义 shortcode），我只复制了 content 没复制 layouts。我看一下 exampleSite/layouts 里有什么。

如上文所述，大部分时候出现报错，AI 会自动检测并查看原因，予以修复（这也是 AI Agent 相比网页聊天式的 AI 更优秀好用的地方），有时候这种溯因会重复好几轮，比如这个 Hugo 重建问题，它尝试解决几次之后发现首页还是 502，于是又开始查找原因：

找到根因了：layouts/index.html（exampleSite 的首页布局）第 4 行 resources is nil ——它依赖 exampleSite 特有的配置/assets，和当前配置不匹配，导致 Hugo 构建失败崩溃退出（502 是因为 Hugo 进程挂了）。另外 docs/shortcodes 和 samples/rich-content 两篇引用了 huggingface/vimeo 远程资源，容器内访问超时拖慢构建。

Rich-content 是国内搭建 Hugo 博客经常碰到的问题，原因是这个示例文章中经常含有引用国内无法访问的远程资源的短代码，造成构建时远程资源访问超时。在之前，我和朋友们经常在这里卡住，需要依靠经验和大量查找才能发现问题，现在 AI 可以直接予以解决。

——和 AI 沟通时：建议一次只改一个位置，有必要时提供截图，报错 Log，并且明确你需要实现的具体效果，避免模糊和抽象表述。连续几次修复无法改善，或者鬼打墙的时候，让 AI 停下来，回退无效的改动，总结当前状态，查看主题文档，尝试重新定位问题。

问题2:怎么只有一个首页？

AI 修复问题之后，我又发现了新的问题：一般的博客站点，至少需要有一个归档页面，才能正常查看文章，但复制了示例站点的 Blog，除了首页之外，我似乎看不到其他内容，于是我问：

这个站点为什么没有 archive 等内容？我只看到了一个首页

现在我明白了问题所在：

1. 首页布局配置：
   1. layout = "profile" — 首页是 profile 布局（个人简介样式，只显示作者信息，不显示文章列表）
   2. showRecent = false — 不显示最近文章
   3. 所以首页只显示 profile，没有文章列表
2. 菜单全部被注释：menus.en.toml 里所有菜单项都是注释状态（#[[main]]），所以顶部没有 Blog/Tags/Categories 等导航链接。用户无法通过菜单访问文章列表/归档。

控制博客名称修改、功能开启的，一般是类似 hugo.toml / config.toml 等名称的文件，有些比较复杂的主题，会把各项配置拆开在不同配置文件里，可以在各个主题的文档中找到具体情况，比如上面这一段指出，在 Blowfish 里 menus.en.toml 决定了博客菜单项的打开与否，当它们全部被注释的时候，页面上就不会显示菜单。

我们可以自己操作或者让 AI 来操作这些文件的修改，有的主题现在会提供 agent skill 来和 AI 协作，这是一种“工作手册”，负责告诉你的 agent 应该遵循什么规则、使用什么工具、按什么步骤来操作主题，比如 Blowfish 在文档中说：

Blowfish 附带一个智能体技能，用于教 AI 编程智能体（如 Claude Code）如何安装、配置该主题并用它构建网站。如果你使用智能体来开发你的网站，安装此技能后，智能体就能熟悉 Blowfish 的配置文件、布局、front matter 和短代码。

让 AI 在主题文件中寻找这个 skill 并使用它，它就可以指导你更好地修改主题。

——注意：使用 AI 来搭建博客，并不意味着我们可以什么都不管，一切都交给 AI 来操作执行。一方面，这样做效率很低下，有一些修改对人类来说只是打开文件改几个字再刷新一下预览，对 AI 来说，它每次都会跑一遍“思考解决办法-搜索文件-修改-反查自检”的流程，token 需要付费，需要使用大量的水和电，相当浪费资源；另一方面，如果完全不了解我们正在做的事情是什么，完全依赖 AI，很容易被 AI 带到沟里，比如 AI 并没有提示我 Blowfish 自带一个 agent skill，如果不读文档，我们就会错过一个现成的，能够更好地解决问题的手段。

通过以上的演示我们其实也可以看出，完全不去了解基础信息，只是让 AI 操作，最终虽然也能获得一定的效果，但非常没有效率，一直碰到问题——这些问题其实都是可以通过一开始读文档，了解主题基本信息之后就解决的，比如刚刚的配置问题，文档中就有明确写明：

设置主题的配置文件

在你的网站根目录中，删除 Hugo 自动生成的 hugo.toml 文件。从主题中复制 *.toml 文件，粘贴到 config/_default/ 目录中。这将确保你的主题设置准确无误，在此基础上你能够轻松地自定义主题。

而入门指南和配置中，有非常详细的教学指导，如果我们提前看到，就能够省下最开始的两轮讨论，直接进入主题——AI 是人类的副驾驶，二者之间应当是协作而不是依赖关系：人类学习得越多，了解得越多，对 AI 的指令越明确，才能让 AI 实现越良好的效果。

问题3:如何开始装修？

接着来介绍一个很实用的功能“选择元素”，在修改站点样式的时候，纯用语言和 AI 比画很容易词不达意，选择元素可以精确地告知对方我们需要修改的对象。在 Workbuddy 中，它的位置在右上角，点击后，鼠标移动到页面上，被选中的部分就会用绿色框起来（没有的话刷新一下页面）。

这时候 Workbuddy 会自动打开 CSS 检查器，我们可以在 CSS 检查器里直接调整布局、外观、字体、颜色等显示，之后点击应用即可把修改内容添加到对话。如果 CSS 检查器内没有你想调整的内容，那么也可以直接点击评论/添加到对话来精确告诉 AI 你想修改的元素（注：主题往往有自适应功能，在不同的宽度提供不同的版面，CSS 检查器会占据宽度，所以打开有时候会挤压原本元素的位置，比如示意图上，打开编辑器时，原本选中的导航栏消失了，这时候拉开宽度就好了）。

部署到网络以及其他

从博客到网站

当本地的博客已经修改好，接下来我们就需要把它推到网络上，真正变成一个网站，我们需要做两件事：

1. 注册一个 GitHub 账号，建立自己的博客 repo（最好选择私人），并且把本地文件夹通过 Git 上传到 GitHub
2. 注册一个 Vercel 账号，关联到自己的博客 repo，触发自动部署。

这方面可以参考2021年博客中的推送到GitHub 内容和搭建博客 内容，只需要在细节上略作修改（原博客是先从 Vercel 进行部署以获得初始博客文件夹，现在是本地已经建好博客，只需要导入 repo），我就不重复赘述了，如果有不明白的地方，可以把这一段以及博客文章发给 AI 以获得详细说明。

如果一切都跑通了，站点也可以在本地正常预览，那么在本地推送内容到线上之后，隔一两分钟，就能在线上看到改动，如果没能成功，很可能是 Vercel 部署失败，可以在 Vercel 的 deployments 页面找到 build log，将报错信息或者平台页面贴给 AI 以定位问题，让它一步一步解决。

需要再次提醒的是，Vercel 自动分配的域名已经被墙阻拦，如果需要优化国内访问，就要自己购置域名，这个也非常多教程了，我写过一篇买域名的记录，可以参考，不过我现在是在 Cloudflare 上管理 DNS（而不是文章中提到的 GitHub），非常推荐，很好用。

如何写博客？

如何写博客也是一个比较多教程的问题了，简单来说，所有的博客文章都是文件夹中的 Markdown 文件，而一篇博客文章分为两个部分，第一部分是上方的 Yaml 区域（被叫作 Front Matter），它负责定义博客的题目、时间、类别、标签等元信息，另一部分是下方的正文。当我们要写一篇新博客的时候，可以使用 Hugo 自带的模板功能来自动套用这些内容，或者也可以从0开始编写。

安装过 Hugo 程序之后（参考安装 Hugo），Git Bash Here（Mac 用户使用终端即可），再输入 hugo server 可以预览站点。

我使用 Obsidian 来管理和编辑博客文章，流程如下：

1. 打开我今天要写的博客文件夹，直接复制上一篇文章，修改副本的标题、YAML 区域，清空正文
2. 使用 Form Flow 插件来简化短代码的填写工作，easy-typing 和 Linter 插件简化排版工作，image auto upload 插件配合 PicGo 实现图片上传。
3. hugo server 预览和检查文章排版，使用 GitHub Desktop 推送更新。

其他顺便提及的内容

• 后台：上文中说到静态博客的缺点是没有一个在线的编辑器，但如果可以接受手写 markdown 格式（或者把其他 markdown 编辑器的内容复制粘贴过来），那么可以试试 pagescms，它会给静态博客提供一个后台，修改后会自动推送到 GitHub 以触发部署，很适合在外改错别字
• 图床：推荐 Cloudflare R2，10G 免费存储空间，非常够用。

AI 与博客的其他可能性

在互联网上搭好了最初的茅草屋之后，通过与 AI 协作，我们还可以实现各种从前因为“不会写代码”而搁置的想法，一座巨大的游乐场！

比如我最近实现的一系列博客大装修：

• 把重复劳动变为自动化：从 NeoDB 到 Blog 的自动化。我的 Chronicle 页面记录了我历年的书影游标记情况，以前，我需要手动书写 YAML 文件来更新表格，在博客中写完点评之后，还要手动给 Chronicle 加上链接。让 AI 写成自动脚本之后，现在实现了在 “NeoDB 标记→自动同步到 Chronicle 页面”和“在文章中提到之后，自动将链接同步至 Chronicle 页面”。
• 重新设计自己的站点：一份来自花边小报的发刊词，用了四年半 cactus 之后，我给了 AI 一份参考图，口述了一系列风格要求，要求它协助我把需求拆分成字体、颜色、留白、版面结构等元素，最终落地成一个崭新的站点主题。
• 为博客加各种功能：在文章中插入轮播图片，曾经我想给博客加入轮播图，但因为不知道这个功能在技术上叫什么，在这一步就卡了好久，但现在只要用自然语言描述，AI 就可以推理出这个功能的实现方式。比如，我只是告诉它，我想要我的女巫飞鱼挂件在页面上四处游走，我们来讨论一下这个功能要怎么实现——于是这个需求被它翻译成一套具体的交互，一些 CSS 和 JavaScript，最终完全达到了我想象中的样子。
• 简化博客的各种操作：手写了五年的 hugo server，最近变成了一个双击即可运行的脚本程序，而我在想，我怎么早没想到这个？新博客的首页需要自己编辑，写 YAML 太麻烦，于是拜托 AI，制作了一个所见即所得的编辑器，往日总是在手动操作很麻烦，专门写一个工具也很麻烦中间反复纠结，AI 降低了这种私人需求的实现门槛，也可以说，是真正让工具来适应自己。

当然啦，和 AI 协作，也不总是一些顺畅、高效的奇迹时刻，生成式 AI 并不能真正理解人类，人类的需求表达，也总是不如想象一般精确、全面。很多时候，AI 确实可以很快地写出一个看起来完美无缺的版本，但真正使用后，却又很快发现：对一个问题的修复引发了另一个问题；看似找到了 Bug 的根因却在反复修改无关代码；有时候已经和它在尖叫我要冬瓜了，它却坚持第五十三次递出一只番茄；只是想做一些非常微小的变动，AI 买芝麻送西瓜，重写了整个区域的实现——新的博客主题写好之后，我整整修 Bug 修了两天，才把从前写的各种排版用的短代码在外部表现上恢复原状。

从这个角度来看，我感觉AI 有点像一个好心肠的猴爪，好心肠体现在许愿过程中它允许我们不断不断地描述需求、检查改动、在方向不对时及时叫停，甚至撤回愿望重新再来。猴爪的部分在于，在实现愿望的时候，经常是以一种出乎意料的方式——而且 每个 token 都要钱，越聪明的模型越昂贵，成本也是一件很重要的事情！

但无论如何，种下一棵树最好的时间是十年前，其次是今天，如果你想在互联网上跑马圈地，真正拥有一个属于自己的博客，最好的时间是2021年来看我的教程（？），其次是今天来看我的教程（？）——AI 并没有让编写代码、搭建博客变成一件不需要思考、不会出错、无脑下命令的事情，人类也需要不断地学习如何更好地表达需求，如何更高效地让 AI 工作——但它确实极大地降低了最开始的技术门槛，从不抱怨你“这都不会”，永远兢兢业业地为你提供指导。我们也可以一步一步地，慢慢地，从不知怎么就搭成了一座茅草房开始，认识砖头，学习瓦工，铺路造林，HTML、CSS、JavaScript，最终筑就一座动森中漂亮的岛屿：我觉得整个过程非常幸福，十分诚意邀请您也来体验。