资源指纹
用 resources.Fingerprint 为资源内容生成哈希文件名与 SRI 完整性值。含哈希与 integrity 的关系、完整示例与常见报错。
开始之前,你需要
- 读过简介,知道资源要经
.Permalink/.RelPermalink才会被发布 - 对浏览器缓存有基本概念:同一个 URL 会被缓存,改了内容却沿用旧 URL 就会拿到旧文件
读完之后你能
- 给 CSS / JS 加上哈希文件名与
integrity属性,让「内容变、文件名就变」自动成立 - 通过对比两次构建的文件名,验证指纹确实随内容变化
- 在浏览器报 SRI 校验失败时,知道先检查管道顺序与文件是否被中间环节改写
这一页解决什么问题
浏览器会缓存 CSS 与 JS。如果你发布的新版本文件名不变,用户可能长时间看到旧样式。指纹解决两件事:
- 缓存失效自动化:文件名里带上内容哈希,内容一变文件名就变,浏览器自然会重新下载;内容不变则文件名不变,可以放心设置很长的缓存时间。
- 子资源完整性(SRI):
integrity属性让浏览器校验拿到的文件是否与预期内容一致,被篡改或被中间环节改写时会拒绝加载。
方法签名与用途
resources.Fingerprint 对资源内容做密码学哈希,返回带哈希值的资源对象,用于缓存失效与子资源完整性校验:
resources.Fingerprint [ALGORITHM] RESOURCE它也有别名 fingerprint。哈希算法可以是 md5、sha256(默认)、sha384 或 sha512。虽然最常见的用途是 CSS 与 JavaScript,但任何类型的资源都可以做指纹。
返回值与边界
| 情形 | 会怎样 |
|---|---|
| 正常 | 返回新资源:RelPermalink / Permalink 里含哈希,.Data.Integrity 含 SRI 值 |
上游是 nil |
该步失败;先 with 判断资源存在 |
| 没做过指纹的资源 | 没有 .Data.Integrity 这项数据,模板里取它会报「无法取值」 |
| 算法写成不认识的值 | 该步失败,报错会指出算法名 |
| 内容为空 | 哈希照样生成,但发布出去是个 0 字节文件——这时该回头找资源路径的问题 |
链式调用示例
{{ with resources.Get "js/main.js" }}
{{ with . | fingerprint "sha256" }}
<script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
{{ end }}
{{ end }}嵌套两层 with 的做法很常见:外层确认资源存在,内层把资源交给指纹环节,同时把 . 绑定到指纹后的资源对象,因此后面可以直接取 RelPermalink 与 Data.Integrity。
Hugo 渲染出的结果大致如下:
<script src="/js/main.62e...df1.js" integrity="sha256-Yuh...rfE=" crossorigin="anonymous"></script>哈希带来的两项变化
对资源内容做哈希之后:
Permalink与RelPermalink返回的路径中包含哈希值,文件名因此发生变化。- 资源的
.Data.Integrity返回一个子资源完整性(SRI)值,由哈希算法名、一个连字符以及 base64 编码后的哈希和组成。
SRI 与指纹的关系
文件名中的哈希与 integrity 属性中的哈希来自同一次计算,但用途不同:文件名哈希让浏览器把改版后的资源当作新文件重新下载,integrity 则让浏览器在加载脚本或样式时校验内容是否被篡改。示例里同时给出的 crossorigin 属性是使用 SRI 时常见的配套写法。
正因为两者同源,管道顺序必须“先压缩、后指纹”。如果先指纹再压缩,integrity 记录的会是压缩前内容的哈希,而实际发布出去的是压缩后的文件,浏览器校验失败就会拒绝加载。
完整可运行示例
这个示例验证「内容变 → 文件名变」这条核心承诺。
① 建项目并进入目录:
hugo new project fingerprint-demo
cd fingerprint-demo② 新建样式 assets/css/main.css:
body {
color: #222;
}③ 新建首页模板 layouts/home.html:
{{ with resources.Get "css/main.css" }}
{{ with . | minify | fingerprint "sha256" }}
<!doctype html>
<html lang="zh-cn">
<head>
<meta charset="utf-8">
<title>Fingerprint 演示</title>
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
</head>
<body>
<h1>资源已加指纹</h1>
</body>
</html>
{{ end }}
{{ end }}④ 第一次构建:
hugo⑤ 改一个字节,再构建:把 #222 改成 #333,然后重新执行 hugo。
你应当看到什么
-
第一次构建后,
public/css/里出现main.<哈希A>.css;页面源代码里<link>的href与之一致,integrity="sha256-…"存在; -
修改颜色并第二次构建后,文件名变成
main.<哈希B>.css,哈希 B ≠ 哈希 A:内容一变,URL 就变,浏览器缓存自动失效; -
第二次构建后,
public/css/里同时存在新旧两个文件。旧文件不会自动消失(Hugo 只是不引用它了),要清理发布目录中的陈旧文件,用:bashhugo --cleanDestinationDir该参数会删除发布目录中本次构建没有产生的文件(
hugo --help中的描述是 “remove stale files from destination”); -
浏览器开发者工具的 Network 面板里,改版后的请求是全新的 URL,状态码为
200而不是304。
缓存与 –gc
资源内容一变,哈希随之变化,文件名也就变了:旧文件名的资源不会自动从发布目录里消失。清理发布目录中的陈旧文件需要用清理目标目录的参数,而 hugo build --gc 负责在构建后清理未使用的缓存文件,两者职责不同,详见命令。
hugo --cleanDestinationDir:发布目录里的陈旧文件(对外可见的那一份);hugo --gc:Hugo 的构建缓存文件(在resources/_gen一类目录里,不对外发布)。
什么时候用 / 什么时候别用
该用的时候
- 交付给浏览器的 CSS、JS、图片等静态资源,希望长期缓存又不担心更新不及时;
- 需要 SRI 校验(安全要求较高的站点);
- 资源链接由模板生成,可以放心随哈希变化。
别用的时候
- 资源路径被别处硬编码,而那个地方不会跟着变——例如 CSS 里写死的
url(/images/logo.png)。Hugo 不会因为图片加了指纹就去改写 CSS 里的路径,两边要各自处理:要么这份资源不加指纹,要么让引用它的那份资源也走管道; - HTML 页面本身:页面 URL 应当稳定可分享,不适合带内容哈希;
- 只在本地调试、不打算配置缓存策略时:指纹会增加心智负担,先跑通再优化。
常见坑
① 命令找不到(命令类)
hugo: command not found:见安装 Hugo;--cleanDestinationDir报「未知参数」:说明 Hugo 版本过老,先用hugo version与hugo --help核对该版本支持哪些参数。不要在不确定时改用删除目录的命令——误删发布目录的代价比多留几个旧文件大得多。
② 没报错但结果不对(静默失败类)
| 现象 | 原因 | 怎么确认 |
|---|---|---|
| 文件名里的哈希一直不变 | 源文件内容真的没变,或构建缓存未失效 | 改一个可见的值再构建;必要时 hugo --ignoreCache |
public/ 里堆了很多旧哈希文件 |
指纹按设计不会删除旧文件 | 用 hugo --cleanDestinationDir 或自行清理 |
| 页面没有样式,控制台报 SRI 错误 | 指纹放在了压缩之前,integrity 对应的是压缩前内容 |
把顺序改成 ` |
模板报「无法取值 .Data.Integrity」 |
这份资源没做过指纹 | 在链上补 ` |
| 引用的图片 404 | 图片被指纹后路径变了,而引用它的地方(如 CSS、行内样式)还是旧路径 | 让引用方也走管道,或对该资源不加指纹 |
③ 报错看不懂(报错类)
浏览器控制台里最常见的两条:
Failed to find a valid digest in the 'integrity' attribute for resource …:integrity与实际文件不匹配。按顺序查:管道是否「先压缩后指纹」→ 发布目录里的文件是否被人为改过 → 是否有 CDN/代理在传输中改写内容;Refused to execute script … because it violates the following Content Security Policy directive:这是 CSP 而不是 SRI,但同样表现为「资源不加载」,检查响应头里的 CSP 配置。
Hugo 构建期的报错则通常是:算法名不合法、上游返回 nil 导致「无法取值」。若报错指向的文件与你改的无关,见故障排查。
排查顺序:资源是否取到 → 管道顺序是否为「压缩后指纹」→ 发布目录里的文件与 integrity 是否一致 → 是否有中间环节改写内容。