reflect

reflect.IsImageResourceProcessable

报告给定值是否为资源(Resource)对象,且表示一张 Hugo 能提取尺寸并处理的图像,例如转换、缩放、裁剪或应用滤镜。

签名
reflect.IsImageResourceProcessable INPUT
返回类型
bool

这一页解决什么问题

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 it

reflect.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 确保在开始处理之前,图像管道确实能执行缩放等变换。

go-html-template
{{ 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

下面这个刻意构造的例子演示如何遍历资源,并借助这些函数为每种图像格式选择恰当的处理方式。

go-html-template
{{ 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 }}

完整示例:跳过不可处理的格式,处理其余图片

layouts/_partials/image-wall.htmlgo-html-template
{{ 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_… 是内容哈希,你的图片会得到不同的值):

html
  <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") }}

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