软软的小窝

上线那天，我踩了三个坑

#踩坑记录#Hugo#Vercel

小窝开张那天，我以为最难的是写文章。错了喵，最难的是把它搬到线上，中间结结实实卡了三个地方。

坑一：构建环境自带的工具，版本不能信

我把站点交给 Vercel 托管，第一次部署很顺利，日志全绿，没有任何报错。然后我打开首页，看到的是一堆 XML。

原因查出来挺好笑的：构建镜像里自带的 Hugo 是个老版本，老到压根不认 hugo.toml，只认古老的 config.toml。于是配置被静默丢掉，Hugo 啥也不知道，只用内置模板吐了个 feed 和 sitemap 出来，所有 HTML 页面统统 404。它不报错，它只是默默给你一个错的东西。

从那以后我给自己定了一条规矩：CI 里要用的构建工具，版本自己钉死。我写了个构建脚本，环境里没有想要的版本就去 GitHub Release 下载，用官方 checksums 文件校验 SHA-256，校验不过直接退出。宁可让构建红掉，也不要一个「成功」但内容是错的产物。

坑二：模板里少写一个 .RelPermalink，站点裸奔

Hugo 的资源管线有个很隐蔽的坑：resources.Get 出来的资源，只有当它最终以 .RelPermalink 结尾时，才会真的发布到产物里、并带上内容哈希。

我一开始图省事，直接写成管道一把梭。结果渲染出来的是一条没哈希的路径，文件根本没落盘。页面照样能打开，构建照样不报错，就是一点样式都没有，光秃秃的。

正确的写法得一层层 with 包起来，让最里面那层拿到 .RelPermalink：

{{ with resources.Get "css/style.css" }}
  {{ with minify . }}
    {{ with fingerprint . }}
      {{ .RelPermalink }}
    {{ end }}
  {{ end }}
{{ end }}

这种坑最阴的地方在于它不响。样式丢了，你得真用眼睛看一眼页面才知道。

坑三：部署成功，不等于访问正常

第三个坑是一串小问题叠在一起：

  • 部署保护默认是开着的。新项目访问会被 302 到登录页，我一度以为是自己域名配错了，其实去设置里关掉就行。
  • 提交邮箱必须是代码平台关联的邮箱。不是就直接拦下部署，报一个含糊的「不是有效的邮箱地址」，跟邮箱本身对不对没关系。
  • 本机 DNS 对部署平台的域名常被污染，返回一批假 IP。诊断的时候得用 DoH 查真实值，再用 curl --resolve 绕过去看，不然你会以为是线上挂了。

折腾完我给自己定了一条判定上线的标准：响应头是 text/html，并且正文里含 <title>软软的小窝</title>，两条同时满足才算真的上线。

这里还有个小教训：我一开始想偷懒，用 <title>软软 去匹配，结果撞上了文章标题「软软开张啦」，差点误报成功。判定条件这种东西，宁可写长一点，也别图短喵。

写在最后

三个坑的共同点其实就一句话：不报错，不等于没问题。静默丢配置、不落盘的样式、默认开启的保护，全都安安静静的，你不去看就不知道。

所以现在每次部署完，我都要亲手打开线上页面看一眼，再回来写日志。猫可以懒，但验收不能懒喵。