一次 Hexo 主题样式事故复盘：本地正常，部署后为什么全乱了

这次故障发生得有点突然。

我刚通过 CMS 更新并部署博客，打开首页后，原本正常的猪头 Logo 被拉成了一条很长的粉色图形，文字也挤到了错误的位置。开始我以为只是浏览器缓存，换了手机，结果还是一样。

问题同时出现在电脑和手机上，说明它不像是某一个浏览器的偶发现象，更可能是部署出去的 HTML 或 CSS 已经出了问题。

一开始走错的方向

看到 Logo 被拉长，最直观的想法是给图片补上固定宽高，再针对手机写一条媒体查询。

这样确实可能暂时把猪头缩回去，但页面里其他元素仍然错位。继续补 CSS，只会把真正的问题盖住。于是我停下了这种修补方式，转而检查 Hexo 实际生成的页面。

我主要对照了三样东西：

1. source 分支中的主题配置；
2. Hexo 本地生成的 public/；
3. GitHub Actions 发布到 main 的最终文件。

如果源码正常而 public/ 已经损坏，问题就在构建阶段；如果本地结果正常而线上不正常，则继续检查部署分支和缓存。

找到不该出现的东西

朋友打开开发者工具后，发现文章页面的一个 post-tools 区域里出现了大量以 $ 开头的变量，以及 +keep-tablet() 之类的内容。

这些本来是 Keep 主题使用的 Stylus 源码，应该在构建时编译为 CSS，不应该作为普通文字出现在 HTML 中。这个线索基本排除了单纯的缓存问题：主题模板或覆盖文件已经不完整，构建仍然成功，却生成了错误页面。

最后的处理

我没有继续给 Logo 叠加样式，而是做了一次完整恢复：

• 撤销临时加入的尺寸和定位补丁；
• 恢复 Keep 主题原本的模板结构；
• 清理旧的 Hexo 数据库和 public/；
• 重新生成整站，并在电脑和手机尺寸下检查首页与文章页；
• 确认 source、main 和正式网站使用的是同一轮构建结果。

完整执行的仍然是熟悉的三步：

hexo clean
hexo generate
hexo deploy

真正重要的不是命令本身，而是 clean。如果继续使用旧的生成文件，很容易把已经修好的源码和残留产物混在一起。

顺手补上的防线

修好以后，我把这次故障变成了自动检查规则。每次发布前，构建程序现在还会确认：

• 主题 CSS 文件没有异常变小；
• 文章工具区生成的是 HTML，而不是 Stylus 源码；
• Logo 保持主题原生的响应式尺寸；
• 页面图片和本地链接都能找到；
• 公式、SEO 元数据、分类和标签页面没有明显错误。

检查失败时，GitHub Actions 会停止发布，正式网站继续保留上一个正常版本。现在通过 Pages CMS 保存文章，也必须经过这道检查。具体发布链路写在 Pages CMS + Hexo 8 实战 中。

这次留下的经验

这次事故最后没有多复杂，但提醒了我三件事：

第一，电脑和手机同时异常时，先检查生成产物，不要急着写响应式补丁。第二，public/ 是构建结果，不应该直接在里面修改。第三，一次故障如果能被机器识别，就应该把它写进发布检查，而不是只靠下次记得。

样式恢复之后，猪头还是原来的猪头。更有价值的是，下一次类似错误应该很难再混进正式网站了。