这两天给站点加学业档案,踩了两个坑。都不是什么高深问题,但都属于“本地一切正常、线上就是不对”的那类,值得记一下。

一、为什么线上和本地预览不一样

现象

推送之后打开线上页面:导航栏是新的,说明 HTML 已经更新;但新加的内容完全没有样式——卡片没有边框,校徽按 SVG 原始尺寸铺满半屏。

本地 localhost 预览却完全正常。

排查

先确认服务器上的文件:

git cat-file -s "origin/main:css/site.css"   # 发布提交里的文件大小

有,大小也对。再看线上页面引用了什么:

<link rel="stylesheet" href="/application.<hash>.css">
<link rel="stylesheet" href="/css/site.css">

关键就在这两行的区别:

  • application.<hash>.css 是主题打包的,文件名带内容哈希,每次构建都会变
  • /css/site.css 是我自己加的补丁样式,文件名永远不变

浏览器缓存的是后者。它可能还存着几次部署以前的版本,那时候还没有新加的那些 class。于是新 HTML 配上旧 CSS,结构在、样式没了。

本地预览没有这层缓存,所以永远正常。

解决

让 URL 跟着内容走。在 Hugo 模板里算文件内容的 MD5:

{{ $siteCssHash := md5 (os.ReadFile "static/css/site.css") }}
<link rel="stylesheet" href="{{ "/css/site.css" | relURL }}?v={{ $siteCssHash }}" />

输出:

<link rel="stylesheet" href="/css/site.css?v=f92eac970bd1dfa87e9f47bf5e30cbf6">

内容变,URL 就变;内容不变,缓存继续有效。比 ?v=时间戳 好:时间戳会让每次构建都强制重新下载,白白浪费。

一个容易误判的细节

排查时我一度以为线上 CSS 少了内容:

$r.Content.Length   # 8884

而本地文件是 9942 字节。差了五百多。

其实 Content.Length 数的是字符,文件大小是字节。中文在 UTF-8 里一个字符占三个字节。把 Content 按 UTF-8 写回文件,正好 9472 字节,和发布版本完全一致。

字符数和字节数不能直接比。

二、多语言站点的链接:页面还是资源?

站点分三种语言:中文在根路径,英文 /en/,法文 /fr/。

Hugo 里有两个很像的函数:

{{ "/undergraduate/shu/" | relURL }}     {{/* /undergraduate/shu/ */}}
{{ "/undergraduate/shu/" | relLangURL }} {{/* /en/undergraduate/shu/ */}}

relURL 只拼 baseURL,relLangURL 才会加当前语言前缀。

我一开始全用了 relURL,结果英文页面点学校卡片,跳回了中文站。修起来很简单,难的是怎么确认没有别的地方也串台。

不能只点首页。构建完之后,按语言把产物扫一遍:

foreach ($l in @("", "en/", "fr/")) {
  $p = "public/${l}undergraduate/index.html"
  Select-String -Path $p -Pattern 'class="school-card" href="[^"]+"' -AllMatches |
    ForEach-Object { $_.Matches.Value }
}

期望每种语言的页面里,站内链接都带自己的前缀:

/undergraduate/shu/
/en/undergraduate/shu/
/fr/undergraduate/shu/

同类的还有 canonical、RSS、sitemap 和语言切换器,都应该一起看。

一条规则

多语言站点的每个链接,先问一句:这是页面还是资源?

  • 页面 → relLangURL,跟着读者当前的语言走
  • 图片、CSS、下载文件 → relURL,全站共用一份

把它当硬规则,比事后逐个修便宜得多。

三、小结

静态站没有服务器,很多事情只能交给浏览器和 CDN。这带来两个后果:

  1. URL 是唯一的版本信号。 URL 不变,就没有版本。所有可能长期存在的资源,都应该内容寻址。
  2. 本地预览不会暴露缓存问题。 “我本地是好的”从来不是证据,构建产物和线上返回的内容才算是。

发布之后别只看首页能不能打开,至少核对一次资源 URL、内容和数量。