reflect.IsImageResourceProcessable
报告给定值是否为资源(Resource)对象,且表示一张 Hugo 能提取尺寸并处理的图像,例如转换、缩放、裁剪或应用滤镜。
这一页解决什么问题
resources.Match "**" 捞出来的图片里,不是每一种都能缩放:SVG 是矢量图,ICO 是图标容器,HEIC/HEIF 需要额外解码支持。如果无条件对它们调用 .Process "resize 300x",构建会中断:
error calling Process: resource "/images/b.svg" of media type "image/svg+xml" does not support this method: use reflect.IsImageResource, reflect.IsImageResourceProcessable, or reflect.IsImageResourceWithMeta to check if the resource supports this method before calling itreflect.IsImageResourceProcessable 就是在调用 .Process 之前的那道门槛:能提取尺寸并做转换/缩放/裁剪/滤镜的资源才返回 true。
什么时候用,什么时候别用
该用:
- 在
.Process、.Resize、.Fill、.Fit、.Crop、.Filters之前守卫; - 批量处理
assets/下混合格式的图片目录(SVG、ICO 很常见)。
别用:
- 只想判断「是不是图片」→ 用 reflect.IsImageResource(它对 SVG、ICO 返回
true); - 想判断「能不能读 Exif」→ 用 reflect.IsImageResourceWithMeta;
- 想判断输出后的图片(
.Process的返回值)能不能再处理 → 上游未说明;对处理结果再次.Process是允许的,但仍应先确认媒体类型。
(0.157.0 新增)
可处理的图像(processable image)
用法
下例遍历项目的全部资源,用 reflect.IsImageResourceProcessable 确保在开始处理之前,图像管道确实能执行缩放等变换。
{{ range resources.Match "**" }}
{{ if reflect.IsImageResourceProcessable . }}
{{ with .Process "resize 300x webp" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="Processed Image">
{{ end }}
{{ end }}
{{ end }}图像操作
用这些函数判断 Hugo 对给定资源支持哪些操作。Hugo 会把多种文件类型都归类为图像资源,但能否处理它们、能否提取元数据,则取决于具体格式。
reflect.IsImageResource:报告给定值是否为资源(Resource)对象,且按其媒体类型判断它表示一张图像。reflect.IsImageResourceProcessable:报告给定值是否为资源(Resource)对象,且表示一张 Hugo 能提取尺寸并处理的图像——例如转换、缩放、裁剪或应用滤镜。reflect.IsImageResourceWithMeta:报告给定值是否为资源(Resource)对象,且表示一张 Hugo 能提取尺寸、并在存在时提取 Exif、IPTC 与 XMP 数据的图像。
下表给出这些函数对各种文件格式的返回值。可以据此判断在模板中调用具体方法之前需要先做哪些检查。
| 格式 | IsImageResource | IsImageResourceProcessable | IsImageResourceWithMeta |
|---|---|---|---|
| AVIF | true | true | true |
| BMP | true | true | true |
| GIF | true | true | true |
| HEIC | true | false | true |
| HEIF | true | false | true |
| ICO | true | false | false |
| JPEG | true | true | true |
| PNG | true | true | true |
| SVG | true | false | false |
| TIFF | true | true | true |
| WebP | true | true | true |
下面这个刻意构造的例子演示如何遍历资源,并借助这些函数为每种图像格式选择恰当的处理方式。
{{ range resources.Match "**" }}
{{ if reflect.IsImageResource . }}
{{ if reflect.IsImageResourceProcessable . }}
{{ with .Process "resize 300x webp" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ else if reflect.IsImageResourceWithMeta . }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ else }}
<img src="{{ .RelPermalink }}" alt="">
{{ end }}
{{ end }}
{{ end }}完整示例:跳过不可处理的格式,处理其余图片
{{ range slice "images/c.png" "images/b.svg" "images/h.ico" "images/a.jpg" }}
{{ with resources.Get . }}
{{ if reflect.IsImageResourceProcessable . }}
{{ with .Process "resize 60x webp" }}<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .MediaType.Type }}">{{ end }}
{{ else }}
跳过(不可处理):{{ .Name }}
{{ end }}
{{ end }}
{{ end }}Hugo 0.167.0 实测渲染为(文件名里的 _hu_… 是内容哈希,你的图片会得到不同的值):
<img src="/images/c_hu_93de2887095100b4.webp" width="60" height="30" alt="image/webp">
跳过(不可处理):/images/b.svg
跳过(不可处理):/images/h.ico
<img src="/images/a_hu_6f77af3c524bf08e.webp" width="60" height="30" alt="image/webp">你应当看到什么:PNG 与 JPEG 被缩放到 60×30 并转成 WebP(.MediaType.Type 实测为 image/webp);SVG 与 ICO 被跳过而不是让构建失败。原图是 40×20,缩放规格 60x 意味着「宽 60,高按比例」,所以得到 60×30。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。样本为 assets/images/ 下用 Pillow 生成的真实文件。
| 输入 | 结果 | 是否报错 |
|---|---|---|
| JPEG、PNG、GIF、BMP、TIFF、WebP、AVIF 资源 | true |
否 |
| SVG 资源 | false |
否 |
| ICO 资源 | false |
否 |
.json、.css、.js 等文本资源 |
false |
否 |
nil(resources.Get 未命中) |
false |
否 |
对 SVG 等直接调用 .Process |
—— | 是:error calling Process: resource "/images/b.svg" of media type "image/svg+xml" does not support this method: … |
| 返回类型 | bool |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | does not support this method: use reflect.IsImageResource… |
对不可处理的格式调用了 .Process/.Resize |
加 reflect.IsImageResourceProcessable 判断,或把该格式排除 |
| 没报错但结果不对 | 缩放后的图被拉变形了 | .Process "resize 60x100" 同时给出宽高时会强拉到精确尺寸(实测 40×20 的图得到 60×100) |
保持比例用 .Fit(实测同参数得到 40×20,不放大),按框裁切用 .Fill(实测得到 60×100) |
| 没报错但结果不对 | 明明能处理的图片被判为不可处理 | 文件其实是 SVG 伪装成 .png,或样本损坏 |
核对 .MediaType.Type,确认文件真实格式 |
| 报错看不懂 | wrong number of args for IsImageResourceProcessable: want 1 got 2 |
内层函数调用没加括号 | 写 {{ reflect.IsImageResourceProcessable (resources.Get "images/a.jpg") }} |
更多排查入口见故障排查。