从 Hexo / Jekyll 迁移到 Hugo：实际踩坑清单（2026-08）

0. 透明披露

• 本文不推广任何云服务、域名或联盟；
• 迁移数据全部来自本人实验性博客，无第三方真实站点数据；
• 不放任何带 PID 的推广链接。

1. 为什么从 Hexo 迁到 Hugo

对 1.6 GiB 内存机器，Hugo 是唯一选择。

2. Front Matter 差异（最容易踩的坑）

Hexo 默认 Front Matter：

1
2
3
4
5
6

---
title: 标题
date: 2026-01-01 12:00:00
tags: [a, b]
categories: [技术]
---

Hugo 默认 Front Matter（TOML 或 YAML）：

1
2
3
4
5
6

---
title: "标题"
date: 2026-01-01T12:00:00+08:00
tags: ["a", "b"]
categories: ["技术"]
---

关键差异：

1. Hexo 时间格式不带时区，Hugo 强烈建议带 +08:00，否则按 UTC；
2. Hexo categories 是单字段，Hugo 是数组；
3. Hexo tags 是数组，Hugo 也必须是数组（单字符串会报错）。

转换脚本（一行 sed）：

1
2
3
4

# Hexo → Hugo：给所有 date 加 +08:00
find source/_posts -name "*.md" | while read f; do
  sed -i 's/date: \([0-9-]* [0-9:]*\)$/date: \1+08:00/' "$f"
done

3. 永久链接（Permalinks）

Hexo 默认：/2026/01/01/title/ Hugo 默认：/title/

要在 Hugo 还原 Hexo 永久链接（保 SEO 继承）：

1
2
3

# config.yaml
permalinks:
  posts: /:year/:month/:day/:slug/

⚠️ 永久链接改了必须同时做 301 重定向，否则百度/Google 全部 404。

4. 文章目录结构

Hexo：source/_posts/标题.md Hugo：content/posts/标题.md

需要手动迁移 + 把文件名 slug 化（去掉中文、保留日期作为前缀）：

1

mv source/_posts/"标题.md" content/posts/2026-01-01-标题.md

5. 标签和分类页

Hexo 自动生成 tags/标签名/、categories/分类名/。 Hugo 默认不生成，需要在模板里手动写：

1
2
3
4
5
6
7

<!-- layouts/taxonomy/term.html -->
<h1>{{ .Title }}</h1>
<ul>
{{ range .Pages }}
  <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>

6. 资源目录（图片）

Hexo：source/_posts/images/foo.png，引用 ![](images/foo.png)。 Hugo：必须放进同名的 index.md 旁边的目录，否则 404：

1
2
3
4

content/posts/标题/
├── index.md
└── images/
    └── foo.png

引用改成 ![](images/foo.png) 不变。

7. 构建脚本

把 Hexo 的 hexo generate 换成 Hugo 的 hugo --gc：

1
2
3
4
5

#!/bin/bash
# build.sh
set -e
/tmp/hugo-bin/hugo --source /path/to/site --gc --minify
echo "build done"

8. 部署方式对比

9. 我的实际选择

• 已完成迁移：12 篇 posts + 12 个工具单页已搬到 Hugo；
• 不保留 Hexo 备库：删除 node_modules，节省 250 MiB 磁盘；
• 下一步：等工具箱 ≥ 15 篇 + 备案通过后，绑定 .com 域名。

10. 常见踩坑 FAQ

Q：Hugo 构建报 “unmarshal error”？ A：99% 是 Front Matter 缩进问题，YAML 不允许 Tab 缩进。

Q：永久链接改完之后旧链接全 404？ A：必须配 Nginx/Caddy 301 重定向，参考 caddy 工具单页。

Q：图片在本地能看，部署后 404？ A：Hugo 的 page bundle 必须用同名目录 + index.md，不能把图片扔到 static/ 就引用。

缺点限制

• Hugo 的 related 推荐算法比 Hexo 弱；
• Hugo 没有 Hexo 的 next/prev 自动生成，需要自写 partial；
• Hugo 主题生态远不如 Hexo，需要自包含 templates。

替代方案

• 继续用 Hexo：内存 ≥ 4 GiB 时完全 OK；
• 迁移到 Astro：构建速度接近 Hugo，但生态更现代；
• 迁移到 Zola：类 Hugo，Rust 写的，国内案例少。

相关

• 《Hugo 静态博客搭建》
• 《从 Hexo / Jekyll 迁移到 Hugo：实际踩坑清单》（重复）
• 《工具箱 / 服务器》