距离上次更新博客，已经过去了一年多。
趁着最近重新拾起写作的念头，我顺手检查了一下博客的技术状态——结果发现积累的问题比预想的要多。这篇文章就记录一下这次升级的过程和踩到的坑。
检查出了哪些问题#
博客用的是 Hugo + Blowfish 的组合。一年多没动，Hugo 和主题都更新了不少版本，配置文件也出现了一些历史遗留问题。
主要发现了以下几类问题：
版本严重滞后
| 项目 | 当时版本 | 最新版本 |
|---|---|---|
| Blowfish 主题 | v2.89.1 | v2.98.0 |
| Hugo（Vercel 部署） | 0.140.0 | 0.156.0 |
更严重的是，Blowfish v2.89.1 之后的版本将 Hugo 最低要求提升到了 0.141.0，而 Vercel 上部署的版本恰好是 0.140.0，意味着每次部署都会触发版本警告，甚至出现功能缺失。
已编译的 CSS 缺失
Blowfish 主题使用 Tailwind CSS v4 构建样式，需要在本地执行 npm 编译后将生成的 assets/css/compiled/main.css 提交到仓库。由于一年多没有更新，这个编译步骤一直没有执行，仓库里这个文件是空的。好在 Vercel 部署不依赖这个文件重新编译（它只运行 Hugo），所以线上样式一直正常——但只要主题升级，这个文件就必须重新生成。
过时的自定义 partial
为了调整文章卡片和元数据的显示，我之前从主题复制了几个 partial 并做了微调。这一年多，主题对这些文件做了相当大的改动，我的版本早已过时：
layouts/partials/article-link/card.html：主题完全重写了图片处理逻辑layouts/partials/article-meta/basic.html：修复了showDateOnlyInArticle的判断逻辑layouts/partials/footer.html：移除了旧版 Hugo resource pipeline 写法（resources.Fingerprint），新版 Hugo 下这段代码会直接报错导致构建失败
其他小问题
categoriesfrontmatter 写成了字符串而非数组（Hugo 期望是数组）- 一篇测试文章
test.md的draft = false，一直处于公开状态 - 版权年份还停在 2024
升级过程#
1. 更新 Blowfish 主题#
主题通过 git submodule 管理，直接切换到 v2.98.0 tag：
cd themes/blowfish
git fetch --tags
git checkout v2.98.0v2.89.1 到 v2.98.0 跨越了 639 个提交，9 个大版本。主要新增功能包括：
- 面包屑导航结构化支持（
enableStructuredBreadcrumbs） - 远程封面图 hotlink 控制（
hotlinkFeatureImage） - TOC bug 修复和多处 RTL 方向适配改进
- Tailwind CSS 升级到
^4.1.18
2. 重新编译 Tailwind CSS#
主题升级后必须重新编译 CSS，否则新版主题的样式类不会生效：
cd themes/blowfish
npm install
cd ../..
./themes/blowfish/node_modules/.bin/tailwindcss \
-c ./themes/blowfish/tailwind.config.js \
-i ./themes/blowfish/assets/css/main.css \
-o ./assets/css/compiled/main.css编译完成后生成了 139KB 的 CSS 文件，提交到仓库。
3. 清理过时的自定义 partial#
对比了三个自定义 partial 与主题新版的差异，发现当初的改动实际上都很小，而主题的更新量很大。决定全部放弃自定义版本，直接使用主题最新版本。
删除 card.html 和 basic.html，用主题新版的 footer.html 覆盖本地版本。
4. 更新配置#
vercel.json 中的 Hugo 版本从 0.140.0 升至 0.156.0，module.toml 中将 extended = false 改为 true 并更新最低版本要求。params.toml 中添加了两个新参数。
5. 清理历史遗留问题#
修复了两篇文章中 categories 字段的类型（字符串改为数组），将测试文章设为草稿，更新版权年份。
构建结果#
本地执行 hugo build，输出：
Total in 137 ms36 个页面，无任何错误。只剩一条可以忽略的警告——主题声明的 max = "0.155.3" 比本地 Hugo 0.156.0 低一个小版本，等主题下次发布时会自动消失。
总结#
这次升级的核心教训是：不要让依赖长时间不更新。如果当初每隔一两个月小幅跟进，每次的改动量会很小，也不会积累这么多自定义 partial 与主题的分叉问题。
另外，自定义主题的 partial 要保持克制——改动越多，跟进上游更新的成本就越高。如果改动很小，有时候不如直接不覆盖，等主题本身支持了再说。
博客重新上线了，希望这次能坚持更新。
