resources

resources.GetMatch

返回路径匹配给定 glob 模式的第一个全局资源;找不到时返回 nil。

签名
resources.GetMatch PATTERN
返回类型
resource.Resource

这一页解决什么问题

有时你知道「有一张封面图」,但不确定它的扩展名是 .jpg、.png 还是 .webp:文件名可能是 hero.jpg,也可能是 hero.webp。resources.GetMatch 让你用 glob 模式代替精确路径,取回第一个匹配的资源——这正好适合「只想要一张图」的场景,例如页面封面、站点 logo。

什么时候用,什么时候别用

该用:

  • 只知道文件名主干与目录,扩展名可能变化;
  • 一个位置只应有一张图(封面、logo、头像),取第一个就够;
  • 想写「有就用、没有就走兜底」的模板。

别用:

  • 路径完全确定 → 用 resources.Get 更直接(还避免「多个文件同时匹配时取到哪个」的不确定性);
  • 需要全部匹配项 → 用 resources.Match;
  • 取页面包里的文件 → 用页面对象的 .Resources.GetMatch。
go-html-template
{{ with resources.GetMatch "images/*.jpg" }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}

Hugo 用大小写不敏感的 glob 模式判断是否匹配。语法规则与示例见 glob 模式速查表。

完整示例:扩展名不确定的封面图

layouts/_partials/cover.htmlgo-html-template
{{ with resources.GetMatch "images/*.JPG" }}{{ .Name }}{{ else }}未匹配到{{ end }}
{{ with resources.GetMatch "images/*.xyz" }}{{ .Name }}{{ else }}未匹配到{{ end }}

Hugo 0.167.0 实测渲染为:

html
/images/a.jpg
未匹配到

你应当看到什么:第一行验证了大小写不敏感——assets/images/a.jpg 是小写扩展名,用 *.JPG 依然匹配到它;第二行验证了未匹配时返回 nil,with 落到 else。想覆盖整个目录时用 images/**(实测能匹配到 images/ 下的资源);模式必须写清目录层级,实测裸写 "*.jpg" 在 assets/ 根层没有 jpg 时返回 nil。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,单语言站点,Windows;assets/images/ 下有 10 个图片资源。

模式 结果 是否报错
"images/*.jpg" /images/a.jpg 否
"images/*.JPG"(大写扩展名) /images/a.jpg——大小写不敏感 否
"images/c.*" /images/c.png 否
"images/*"(多个匹配) /images/g.webp——不是文件名第一个(上游未说明取哪个) 否
"images/*.xyz"(无匹配) nil,with 判假 否
返回类型 resource.Resource,或 nil 否

常见坑

类别 症状 真因 怎么修
没报错但结果不对 页面上的封面图不是预期的哪一张 目录里有多张图都符合模式,取到了不确定的一个 改成确切路径的 resources.Get,或让模式更具体
没报错但结果不对 明明有图却匹配不到 模式没有覆盖到文件所在层级(实测 "*.jpg" 在 assets/ 根层无 jpg 时为 nil,而 "images/*.jpg" 命中),或扩展名拼错 把目录写进去,用 "images/*.jpg";需要整层时用 "images/**"
报错看不懂 does not support this method: use reflect.IsImageResource… 匹配到的不是图片(例如 images/* 命中了 .svg),却取了 .Width 用 reflect.IsImageResource 守卫,或把模式限定到具体扩展名
没报错但结果不对 取不到页面包里的图 用了 resources.GetMatch 而不是 .Resources.GetMatch 页面资源用页面的 Resources 方法

更多排查入口见故障排查。