【网站搭建】静态资源的缓存与多语言链接
这两天给站点加学业档案,踩了两个坑。都不是什么高深问题,但都属于“本地一切正常、线上就是不对”的那类,值得记一下。
一、为什么线上和本地预览不一样
现象
推送之后打开线上页面:导航栏是新的,说明 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。这带来两个后果:
- URL 是唯一的版本信号。 URL 不变,就没有版本。所有可能长期存在的资源,都应该内容寻址。
- 本地预览不会暴露缓存问题。 “我本地是好的”从来不是证据,构建产物和线上返回的内容才算是。
发布之后别只看首页能不能打开,至少核对一次资源 URL、内容和数量。
相关技能
- Hugo
- Git
- Linux