文档章节
资源函数
用这些函数处理资源。
这一页解决什么问题
Hugo 把「可加工的文件」统一叫做资源(Resource),来源有三类:
- 全局资源:
assets/目录(或挂载到它的目录)里的文件; - 页面资源:页面包(leaf bundle,含
index.md的目录)里的文件; - 远程资源:
resources.GetRemote抓回来的文件。
资源与 static/ 里的文件最大的区别是:资源可以被读取内容、被加工(压缩、加指纹、拼接、当模板执行、图片缩放),而 static/ 只是原样拷贝。本章这组函数就是「取资源」与「造资源」的工具箱。
什么时候用,什么时候别用
| 你想做的事 | 用哪个函数 |
|---|---|
| 按路径取一个资源 | resources.Get |
| 按 glob 取第一个匹配的资源 | resources.GetMatch |
| 按 glob 取全部匹配的资源 | resources.Match |
按媒体类型大类取资源(image、text…) |
resources.ByType |
从字符串造一个资源(如 security.txt、内联 CSS) |
resources.FromString |
| 把资源当 Go 模板执行(CSS 里插站点参数) | resources.ExecuteAsTemplate |
| 压缩 CSS/JS/JSON/HTML/SVG/XML | resources.Minify |
| 给资源加内容哈希指纹(缓存失效) | resources.Fingerprint |
| 把多个同类型资源拼成一个 | resources.Concat |
| 复制/改名资源 | resources.Copy |
| 把资源写进发布目录 | resources.Publish |
| 从 URL 取远端文件 | resources.GetRemote |
| 构建之后再处理资源(已弃用) | resources.PostProcess |
什么时候别用:
- 文件只需要原样发布、不做任何加工 → 放进
static/,不必经过资源管道; - 只是想给图片加样式 → 用
assets/+ 图片处理方法,或直接用static/的固定路径; - 想解析 JSON/YAML/CSV 的内容 → 先取到资源,再交给
transform.Unmarshal;resources.*系列不解析内容。
完整示例:取资源 → 压缩 → 加指纹 → 输出
layouts/_partials/head.htmlgo-html-template
{{ with resources.Get "css/main.css" }}
{{ with . | minify | fingerprint "sha256" }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}">
{{ end }}
{{ end }}assets/css/main.css 的内容是:
css
/* teach demo stylesheet */
body {
margin: 0;
color: #222;
}Hugo 0.167.0 实测渲染为(哈希取决于文件内容,你的站点会不同):
html
<link rel="stylesheet" href="/css/main.min.adf1c26ee231057476e47c3f836f8e9bb1d485d2596b98bd625b88113304bc85.css" integrity="sha256-rfHCbuIxBXR25Hw/g2+Om7HUhdJZa5i9YluIETMEvIU=">你应当看到什么:文件名里多了 .min. 与一串 64 位哈希(sha256 的十六进制),integrity 则是 算法名- 加 base64。注意 integrity 里的 + 被输出成 +——HTML 属性会做实体转义,浏览器解码后是同一个 base64 值,SRI 校验不受影响。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。细则见各函数页,这里是最常踩的几条:
| 情况 | 结果 | 是否报错 |
|---|---|---|
resources.Get/GetMatch/Match 找不到 |
返回 nil/空集合(with、if 判假) |
否 |
resources.Concat 传入不同媒体类型 |
返回失败 | 是:resources in Concat must be of the same Media Type, … |
resources.Minify 用在不支持的类型上 |
调用时不一定报错,读取内容时失败:minifier does not exist for mimetype |
是 |
resources.Fingerprint 算法拼错 |
读取 .RelPermalink 时失败:unsupported hash algorithm: "sha1", use either md5, sha256, sha384 or sha512 |
是 |
| 资源未被引用也没有显式发布 | 文件不会出现在 public/ |
否 |
.Publish 方法的结果 |
实测为 <nil>,不能链式取 .RelPermalink |
是(链式时) |
resources.Publish 函数传入 nil |
—— | 是:<nil> can not be published |
读完本章你应该能够
- 区分全局资源、页面资源、远程资源,并选对获取方式
- 用
minify+fingerprint搭出一条缓存安全的静态资源管道 - 知道
resources.Get找不到时返回nil,并用with兜住 - 说清
resources.Publish与资源的.RelPermalink/.Permalink在「何时写文件」上的关系
阅读顺序
- resources.Get、resources.GetMatch、resources.Match、resources.ByType —— 先把资源取出来;
- resources.Minify、resources.Fingerprint、resources.Concat —— 加工与打包;
- resources.FromString、resources.ExecuteAsTemplate、resources.Copy —— 造资源;
- resources.Publish、resources.PostProcess —— 发布时机;
- resources.GetRemote —— 远端资源(需要联网,注意安全与缓存)。
更多排查入口见故障排查。
本章内容
- resources.ByType 返回给定媒体类型的全局资源集合;一个都没有时返回 nil。 (今天)
- resources.Concat 返回拼接后的资源切片。 (今天)
- resources.Copy 返回给定资源在目标路径上的副本。 (今天)
- resources.ExecuteAsTemplate 返回由 Go 模板创建的资源,它用给定上下文解析并执行。 (今天)
- resources.Fingerprint 返回带指纹的资源,它由给定资源的内容做密码学哈希得到。 (今天)
- resources.FromString 返回由字符串创建的资源。 (今天)
- resources.Get 返回给定路径上的全局资源;找不到时返回 nil。 (今天)
- resources.GetMatch 返回路径匹配给定 glob 模式的第一个全局资源;找不到时返回 nil。 (今天)
- resources.GetRemote 返回给定 URL 上的远程资源;找不到时返回 nil。 (今天)
- resources.Match 返回路径匹配给定 glob 模式的全局资源集合;一个都没有时返回 nil。 (今天)
- resources.Minify 返回给定资源压缩后的版本。 (今天)
- resources.PostProcess 返回在构建之后才处理的资源。 (今天)
- resources.Publish 发布给定资源后返回该资源。 (今天)