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.mjsscripts/:保留构建辅助脚本(内容预处理、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 = 85. 图标要显式注册
主题用的是 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,希望这篇能帮你少踩几个坑。