我用Hugo搭博客踩过的那些坑

2026年6月6日

说实话，我之前一直用WordPress，觉得挺好的啊，可视化编辑，插件多，想加啥功能都有。

直到上个月某天，我网站突然打不开了...

后台进不去，前台白屏，数据库连不上。我当时就懵了，花了整整一天才搞定。从那以后我就琢磨着换静态博客。

为什么选Hugo

网上搜了一圈，Hexo、Gatsby、Hugo这几个比较火。我选Hugo纯粹是因为——快。

真的，Hugo生成几千篇文章只要几秒钟，这速度我服了。而且Go写的，单文件，不用装Node.js那一套（我Node版本管理已经够乱了...）

安装过程比想象中顺利

Windows上直接用 Chocolatey：

choco install hugo -y

或者用 Scoop 也行：

scoop install hugo-extended

我两个都试了，推荐用 extended 版本，后面处理图片和SCSS会方便很多。

第一个坑：主题选择困难症

Hugo官方主题库里几百个主题，我挑了整整两天...

最后选了 PaperMod，简洁、响应式、SEO友好。关键是文档全，遇到问题能找到答案。

不过说实话，主题这东西真的看个人喜好。我朋友看了我选的这个主题，说太朴素了，然后他选了个花里胡哨的，结果加载速度慢得要死...

第二个坑：本地图片处理

这个坑我真踩大了。

一开始我把图片直接扔进 static/images/ 目录，然后在文章里用 ![alt](/images/xxx.jpg) 引用。看起来没问题对吧？

问题来了——图片多了以后，static 目录乱得像我家衣柜...

后来发现Hugo支持Page Bundles，可以把图片和文章放在一起：

content/
  posts/
    my-article/
      index.md      # 文章正文
      image1.jpg    # 图片可以放这里
      image2.png

然后在文章里用 ![alt](image1.jpg) 就能引用，清爽多了！

第三个坑：部署到Netlify失败

本地跑得好好的，hugo server 一切正常。

推到GitHub，Netlify自动构建，然后...失败了。

报错信息看了一脸懵逼：Error: Unable to locate config file or config directory

折腾了半天才发现，我本地用的是Hugo 0.110.0，Netlify默认用的最新版。版本不兼容导致配置文件读不了。

解决方法是在仓库根目录建个 netlify.toml：

[build.environment]
  HUGO_VERSION = "0.110.0"

或者你也可以跟进最新版，但我懒得改配置，就锁定了旧版本...

现在用下来怎么样

说实话，真香。

网站加载速度快得飞起，服务器成本几乎为零（Netlify免费额度够用），再也不用担心被黑客爆数据库了（静态页面有啥可黑的...）

写作体验也不错，我用VS Code + Markdown All in One 插件，写起来很顺手。

唯一的缺点是，想加评论系统得用第三方（我用的 Giscus，基于GitHub Discussions，挺好用的）。还有搜索功能也得自己搞，不过有 官方教程，照着做就行。

给新手的几个建议

1. 别在主题上浪费太多时间。选个简洁的，先把内容写出来，网站做好了再慢慢改。
2. 早点学Git。我之前只会 git add . 和 git commit -m "update"，遇到冲突就慌。现在至少知道怎么回滚了...
3. 备份！备份！备份！ 我就因为没备份，丢失过两篇文章。现在用Git + GitHub私有仓库，双重保险。

好了，就写这么多。我去继续写下一篇文章了～

P.S. 如果你也在用Hugo，遇到啥问题可以留言，我踩过的坑说不定能帮你省点时间😂