Hugo Stack v4 迁移地图

本文是一次真实迁移的完整走查记录（一次性、面向人阅读）。可被 AI 直接调用、带可复用 verify 的精简版，见知识卡片 hugo-stack-v4-migration-map（/ai/cards/hugo-stack-v4-migration-map.md）。

背景

把本博客从 Stack v3 升级到 v4。验证于 2026-06-03 UTC（北京时间 2026-06-04），环境为 WSL。适用场景：升级本博客或其他基于 Stack 主题的 Hugo 站点到 v4，尤其当出现 CI 卡住、自定义 partial 消失、link-card 页面在构建期抓取远程图片、或旧 frontmatter 不再影响页面可见性时。

迁移地图

Hugo 版本下限：Stack v4 要求 Hugo >=0.157.0；本博客 CI 使用 0.162.1。
模块路径：导入 github.com/CaiJimmy/hugo-theme-stack/v4，并在 go.mod 中 require github.com/CaiJimmy/hugo-theme-stack/v4 v4.x。
Partial 覆盖：Stack v4 使用 layouts/_partials/**，而非 layouts/partials/**。把自定义 partial 移到那里。
语言键：简体中文是 zh，不是 zh-cn；使用 locale = "zh" 与 defaultContentLanguage = "zh"。
Favicon：设置 favicon = "favicon.ico" 并把文件放到 assets/ 下；仅为了向后兼容旧 URL 才保留 static/favicon.ico。
侧栏头像：v4 期望 [sidebar] avatar = "img/avatar.jpg"，而非 v3 的 [sidebar.avatar] enabled/local/src 对象。
图片处理：v4 把 imageProcessing.cover 改名为 imageProcessing.thumbnail；内容图片处理仍保留 [imageProcessing.content]。
隐藏页面：v4 移除了 Stack 的 hidden frontmatter 行为。对必须不出现在列表中的页面，改用 Hugo 构建选项，例如 build.list = "never"。
菜单图标：使用菜单 params.icon；不要再依赖 .Pre。
OpenGraph 默认图：v4 去掉了旧的默认回退配置；移除 [defaultImage.opengraph]。
排序：v4 支持 SortBy = "lastmod"。为了 CI 行为稳定，配合 enableGitInfo = true、完整的 checkout 历史，以及 [frontmatter].lastmod = ["lastmod", "modified", ":git", "date", "publishDate"]。
Link-card 图片：v4 原生 links 组件会在 Hugo 构建期抓取远程 link 图片。对本博客，覆盖 article/components/links.html，直接渲染 <img src="...">，让浏览器加载 favicon，CI 不依赖远程站点。

可用 v4 原生能力替换

Markdown alerts 通过 [article.alertIcon] 原生支持；普通 note/tip/warning 块不再需要自定义 admonition shortcode。
Mermaid 代码块通过 [article.mermaid] 原生支持；图表不再需要自定义 Mermaid shortcode 或页面级加载器。
文章内容中的外部图片现在参与 Photoswipe v5 画廊/灯箱。
当默认布局够用时，通用 taxonomy 组件可替换定制的 category/tag 组件。
当目标是“最近编辑”排序时，SortBy = "lastmod" 可替换本地的列表 hack。
Comentario 与 GDPR cookie consent 是原生选项，但仅在站点有相应隐私/评论政策时才启用。

需要保留的自定义

APlayer 音乐播放器，包括自动列表注入与固定播放 UX。
自定义搜索 query-param 行为。
Mastodon 想法时间线。
分享按钮。
密码保护的公开文章包装。
CI 友好的、构建期稳定的 link-card 图片渲染。

迁移清单

在逐个修报错之前，先读官方 v4 升级指南与本地 v4 默认配置。
更新 Hugo、模块路径、go.mod、go.sum、语言键、favicon、头像、图片处理，以及被移除的配置块。
把自定义 partial 从 layouts/partials/** 移到 layouts/_partials/**；同步更新任何 workflow 路径（例如 music sync）。
扫描 content/frontmatter 中的 hidden: true、imageProcessing.cover、 layouts/partials/、.Pre，以及被误写成 Markdown 图片的普通链接。
用接近空的缓存、以 CI 的 Hugo 版本构建；远程抓取警告通常意味着某个非图片 URL 被当作图片，或 links partial 在构建期做了远程工作。
用 Playwright MCP 走查首页、搜索、关键自定义页面、link-card 页面、一篇文章页面，以及一个移动端视口。

验证

1
2
HUGO_ENVIRONMENT=production hugo --minify --baseURL https://lihan3238.github.io/ \
  && actionlint && git diff --check

期望：Hugo >=0.157 无警告构建；workflow 通过 lint；diff 无空白错误；合并前 PR 的 Pages 构建通过。若失败，检查模块路径、partial 覆盖位置、 avatar/favicon/imageProcessing 键、隐藏 frontmatter，以及构建期远程资源抓取。