1239 字
6 分钟
把 Fuwari 从 Astro 移植到 Hugo:过程、踩坑与经验

Fuwari 是我很喜欢的一个博客主题,原版是基于 Astro 的。用了一段时间后,我决定把它整体移植到 Hugo,这篇文章记录整个过程和踩过的坑,给想做类似事情的人参考。

为什么移植到 Hugo#

  • Hugo 是单个二进制,不需要 Node 运行时就能构建,部署环境更简单。
  • 构建快:这个站 11 个页面,Hugo 构建不到 0.2 秒。
  • 模板能力够用:Hugo 的 partial + 模板函数基本能还原 Astro 组件的逻辑。

移植不是”翻译”那么简单,Astro 的组件模型、配置体系、构建流程都和 Hugo 不一样,很多地方要重新设计。

移植范围#

原仓库的 Astro 源码全部移除,替换成 Hugo 实现:

  • layouts/:Astro 组件(.astro)全部改写成 Hugo 的 partial / 模板
  • hugo.toml:替代原来的 src/config.ts 和 astro.config.mjs
  • scripts/:保留构建辅助脚本(内容预处理、Tailwind CSS 编译)
  • data/icons.json:图标库(Iconify)
  • src/content/:文章与页面内容

几个核心差异#

1. 配置从 TypeScript 变成 TOML#

Astro 版所有配置都在 src/config.ts 里,用 TypeScript 对象写。Hugo 版拆到了 hugo.toml:站点信息、[params.profile](个人资料)、[params.navbarLinks](导航)、[frontmatter](日期字段映射)等。

[params.profile]
avatar = "https://github.com/cleeate.png"
name = "cleeate"
bio = "个人博客。"
[[params.profile.links]]
name = "GitHub"
icon = "fa6-brands:github"
url = "https://github.com/cleeate"

2. 内容目录不是 content/#

这是最容易踩的坑之一。Hugo 默认读 content/,但这个主题的 hugo.toml 里写了:

contentDir = ".hugo/content"
staticDir = ["public", ".hugo/static"]

也就是说,Hugo 不直接读 src/content/。构建时先由 scripts/prepare-content.mjs 把 src/content/ 复制并预处理到 .hugo/content/(丢弃 config.ts、预渲染代码块),Hugo 再从那里读。

所以如果手动跑 hugo 而没先跑 prepare-content,hugo list all 只会输出一个表头、一篇文章都没有。这个坑我第一次就踩了。

3. return 每个 partial 只能有一个#

这是最坑的一个。Hugo 的 return 语句有个硬限制:每个 partial 文件只允许一个 return,且必须在最后。原 Astro 移植版里有几个递归 partial(sectionize-recurse.html、github-cards.html)在 if/else 分支里各写了一个 return,构建时直接崩:

at <return>: wrong number of args for return: want 0 got 1

这个错误很迷惑,因为 return $var 看起来完全合法。原因就是 Hugo 只认”最后一个 return”,中间的分支 return 会被当成普通函数调用。解决办法是重构成”变量累积 + 末尾单一 return”:

{{- $result := "" -}}
{{- if not $heads -}}
{{- /* 处理 */ -}}
{{- $result = $out -}}
{{- else -}}
{{- /* 处理 + 递归 */ -}}
{{- $result = partial "sectionize-recurse.html" (dict ...) -}}
{{- end -}}
{{- return $result -}}

4. paginate 在 Hugo 0.128+ 已移除#

旧配置里的 paginate = 8 在新版 Hugo 会直接报错(不是警告):

site config key paginate was deprecated in Hugo v0.128.0 and subsequently removed.

要改成:

[pagination]
pagerSize = 8

5. 图标要显式注册#

主题用的是 Iconify 图标,但渲染时只认 data/icons.json 里已存在的图标——没有的话静默不渲染(不报错)。所以导航项配了 icon = "material-symbols:home",如果图标库里没有 material-symbols:home,那个图标就是空白。

补图标的方式是从 Iconify API 拉 SVG body 合并进 data/icons.json:

https://api.iconify.design/material-symbols.json?icons=archive,build-outline,image-outline

功能增强#

移植过程中顺手加了几个原版没有的功能:

  • 导航下拉子菜单:给 navbar.html 和移动端菜单加了 children 渲染,支持”工具 → 图床”这种下拉。桌面端 hover 显示,箭头旋转 + 面板淡入上移的动效。
  • 菜单图标:每个导航项前面带小图标,和原版 Astro 一致。
  • 单 return 重构:修掉了上面说的构建崩溃。

性能优化#

移植完做了一次真实的加载分析(Performance API),首屏实际下载 176KB、831ms。做了两个优化:

  • Pagefind 延迟加载:搜索库从”DOMContentLoaded 立即加载”改成 requestIdleCallback 空闲时加载,不再阻塞首屏。
  • preload 关键资源:给 main.css 和正文字体加 <link rel="preload">,让浏览器更早抓取。

优化后首屏降到 149KB / 764ms。CF Pages 自带 gzip/brotli,HTML 实际传输只有 11.4KB——压缩这块其实已经到位,没必要再折腾 minify。

文档也要跟上#

移植最容易忽略的是文档。代码全改完了,README 和写作指南里还是”npm create fuwari、编辑 src/config.ts、pnpm dev 在 4321 端口、输出到 ./dist/”——全是 Astro 的。这类残留对使用者误导极大。移植时把 README、写作指南、贡献指南都 Hugo 化了一遍,翻译版只保留中英文。

部署#

  • 博客站:Cloudflare Pages,构建命令 pnpm build,输出 public/,Node 22。
  • 主题演示站:GitHub Pages,用 GitHub Actions 自动构建部署。

总结#

Astro → Hugo 的移植,代码量不算大,但细节坑非常多:return 单语句限制、paginate 废弃、contentDir 指向生成目录、图标要显式注册、文档残留……每一个都可能让你卡半天。

移植完成后,构建速度和部署简单性都有明显提升,主题功能也完整保留。如果你也想把某个 Astro 主题搬到 Hugo,希望这篇能帮你少踩几个坑。

把 Fuwari 从 Astro 移植到 Hugo:过程、踩坑与经验
https://npq.kdns.fr/posts/hugo-fuwari-port/
作者
cleeate
发布于
2026-11-13
许可协议
CC BY-NC-SA 4.0