404 Vercel 部署 Hugo排查实录

“最让人崩溃的 Bug，往往不是代码写错了，而是环境对不上了。”

在构建 V3版本的过程中：GitHub 提示 Push Success，Vercel 提示 Deployment Complete，但当点开域名时，看到的却是冰冷的 404 Page Not Found。

一：消失的页面

1. 本地预览完爆：运行 hugo server -D 时，一切排版、音乐组件、五条悟背景都运行得丝滑顺畅。
2. 仓库同步正常：GitHub 上的源码确实是最新的。
3. 线上死火：Vercel 虽然显示绿色的 Ready，但页面像被黑洞吞噬了一样，只有一片空白或 404。

二：在日志中寻找

在Vercel 的 Build Logs。在翻阅了几百行编译日志后，我发现了几行红字标注的错误：

ERROR render of "..." failed: "...": execute of template failed: ... can't evaluate field Locale in type *langs.Language

报错透露了一个关键信息：Vercel 的编译器不认识 Locale 这个字段。

为什么会这样？

经过排查，我找到了问题的根源：

• 我所使用的 PaperMod 主题，使用了 Hugo 近期版本才引入的新特性（如多语言支持、现代资源管道）。
• Vercel 的默认环境：如果你不手动指定，Vercel 往往会调用一个极低版本的 Hugo 镜像（可能是 0.5x 甚至更老）。
• 版本代沟：老版本的 Hugo 面对新版本的代码，就像是在用秦朝的法律审判现代的案件——完全对不上号。

三：环境变量注入

既然找到了病根是“版本太低”，解决思路就很清晰了：强迫 Vercel 升级。

我通过以下三个步骤：

1. 确定版本：在本地终端输入 hugo version，确认我本地运行正常的版本号（例如 0.130.0）。
2. 设置环境变量：进入 Vercel 项目后台，找到 Settings -> Environment Variables。
3. 精准注入：
   • Key: HUGO_VERSION
   • Value: 0.130.0
4. 触发重部署：保存设置后，重新进行 Redeploy。

守得云开见月明

随着蓝色圈圈的再次转动，这次日志里不再有红色的报错，取而代之的是 Building Site... Success!。

刷新页面，终于不再是404。

经验总结

这次 404 事故给了我两个深刻的教训：

• 环境一致性：开发环境（本地）与生产环境（云端）的版本必须严格对标。
• 日志分析：当网站出问题时，别急着改代码，先看日志，那里藏着所有的答案。

如果你也遇到了 Hugo 部署后样式崩坏或 404，别怀疑自己，先去看看 Vercel 的环境变量里，是不是还缺了那行 HUGO_VERSION。

[ System Status: Fully Operational ]
[ Version: V4.0 Stable ]