图像处理
图像资源处理方法、成像配置与响应式图片生成;含输出文件名规则、验证方法与常见坑。
开始之前,你需要
- 读过页面资源,知道
.Resources与resources.Get的区别。 - 站点里至少有一张真实图片可以拿来试(不是占位文本文件)。
读完之后你能
- 把图片捕获为页面资源、全局资源或远程资源,并用
.Resize/.Fill/.Process等生成新图片; - 在产物目录里认出处理后的图片文件名,用构建统计确认处理确实发生了;
- 用
[imaging]配置统一各格式的质量与缩放算法; - 用一次处理 +
srcset生成响应式图片,避免在模板里重复处理。
这一页解决什么问题
Hugo 可以在构建过程中转换与分析图像。任何图片格式都能作为资源管理,但只有可处理的图像(processable image)才能用下文的方法转换;处理结果会写入缓存,以保证后续构建依旧很快。判断一张图片能否处理,用 reflect.IsImageResourceProcessable 函数。
图像处理的坑几乎都不在「方法怎么调」,而在结果去了哪里:处理后的图片是新文件、名字带哈希,和源图不在同一个名字上。本页给出一条能自己验的路径:
- 先捕获资源(页面资源 / 全局资源 / 远程资源);
- 再调用方法,拿到一个新的资源对象;
- 用新对象的
.RelPermalink输出——直接用源图地址是看不到处理结果的。
验证图像处理是否发生,两步:
hugo你应当看到什么(实测:Hugo 0.167):构建统计里出现一行 Processed images │ N,N 就是本次真正处理的图片数量;产物目录里同时出现带哈希后缀的新文件,例如
public/images/a_hu_c87d9bcee87f980.png ← .Resize "1x" 的结果
public/images/a_hu_952889bdd5894091.webp ← .Process "webp q60" 的结果命名规律是 原文件名_hu<哈希>.<扩展名>,发布位置沿用资源原本的目录(assets/images/a.png → /images/…)。同一张图用不同规格处理会得到不同哈希的不同文件,所以不要按固定文件名去引用处理结果,一定要用模板里拿到的 .RelPermalink。
还可以先在模板里自查可处理性:
{{ reflect.IsImageResourceProcessable (resources.Get "images/a.png") }}你应当看到什么:输出 true 才说明这张图能转换。若为 false,后面所有 .Resize 一类调用都没有意义。
图像处理概览
Hugo 可以在构建过程中转换与分析图像。任何图片格式都能作为资源管理,但只有可处理的图像(processable image)才能用下文的方法转换;处理结果会写入缓存,以保证后续构建依旧很快。判断一张图片能否处理,用 reflect.IsImageResourceProcessable 函数。
捕获三种图像资源
要处理图像,先把它捕获为页面资源(page resource)、全局资源(global resource)或远程资源(remote resource)。
页面资源是与叶子包 index.md 放在同一目录的图片,用页面对象的 .Resources 取得:
{{ $image := .Resources.Get "sunset.jpg" }}全局资源放在项目的 assets 目录中,用 resources.Get 取得:
{{ $image := resources.Get "images/sunset.jpg" }}远程资源用 resources.GetRemote 按 URL 取得:
{{ $image := resources.GetRemote "https://example.org/images/sunset.jpg" }}相关概念见页面资源。
渲染图像
捕获资源后,用 .Permalink、.RelPermalink、.Width、.Height 等方法把图片写进模板。资源不存在时,可以直接抛错,也可以用 with 跳过渲染:
{{ with .Resources.GetMatch "sunset.jpg" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}远程资源还可能取回失败,可用 try 区分错误与结果:
{{ $url := "https://example.org/images/sunset.jpg" }}
{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else with .Value }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ else }}
{{ errorf "无法获取远程资源 %q" $url }}
{{ end }}
{{ end }}处理方法
处理方法作用于图像资源,Hugo 按需生成处理结果、写入缓存并返回一个新的资源对象:
{{ with .Resources.Get "sunset.jpg" }}
{{ with .Resize "400x" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}可用的方法如下:
| 方法 | 作用 |
|---|---|
.Resize |
按给定规格缩放,只给宽度或高度时保持宽高比 |
.Fit |
缩放至完全放入给定尺寸,保持宽高比 |
.Fill |
先按比例缩放再裁剪,填满给定尺寸 |
.Crop |
按给定尺寸与锚点裁剪 |
.Filter |
应用滤镜,如模糊、亮度、对比度等 |
.Process |
用一条处理规格字符串完成缩放、裁剪、旋转与格式转换 |
.Colors |
提取图像的主色调,按占比从高到低排列 |
.Meta |
读取图像的 Exif、IPTC 与 XMP 元数据 |
.Meta 自 Hugo 0.155.3 起提供,可用 reflect.IsImageResourceWithMeta 先做判断,返回对象上可取日期、纬度、经度、方向(.Date、.Lat、.Long、.Orientation)等值;它取代了旧版的 .Exif 方法(自 0.155.0 起弃用)。规格字符串的常见写法有 "600x"(宽度固定、高度按比例)、"x400"(高度固定)与 "600x400"(目标尺寸);.Fill 与 .Crop 还会用到锚点(anchor),它决定裁剪时保留图片的哪个部位。
注意:图像转换不会保留元数据,要读取元数据必须对原始图像资源调用 .Meta。
上表只列出最常用的方法,完整清单与各自的参数见 Resource 方法。
返回值边界(判断「没图」还是「写错了」):
| 写法 | 资源不存在或不可处理时 | 会不会报错 |
|---|---|---|
{{ with .Resources.Get "sunset.jpg" }}…{{ end }} |
整块跳过 | 否 |
{{ with .Resize "400x" }}…{{ end }} |
整块跳过 | 否 |
{{ .Resources.Get "sunset.jpg" }} 后直接点 .Width |
nil 上取字段 |
是(nil pointer evaluating) |
{{ with .Colors }} |
空切片,with 判假 |
否 |
{{ with .Meta }} / {{ .Meta.Date }} |
不可处理或没有元数据时取不到值 | 取决于是否链式取值 |
远程资源 resources.GetRemote 失败 |
用 try 区分 .Err 与 .Value;不处理会得到 nil |
否(可由 errorf 主动抛错) |
什么时候用图像处理、什么时候别用
该用:
- 同一张原图要输出多个尺寸(响应式
srcset); - 需要统一转格式(例如全部转 WebP/AVIF)或压缩质量;
- 需要按固定版式裁剪(封面图统一
16:9)。
别用:
- 源图远大于实际发布尺寸——构建时的内存与时间随图像尺寸增长,一张 4032×2268 的图远比 1920×1080 昂贵;应在构建前先把源图缩小,而不是交给 Hugo 每次构建去缩;
- 只需要原样输出的图片——直接放进
static/或作为普通资源引用即可,不需要经过处理管线; - 想用处理方法来「加水印/合成」复杂图像——Hugo 的图像滤镜能力有限(缩放、裁剪、旋转、格式转换与基础滤镜);复杂合成请在外部完成;
- 以为处理结果会保留元数据——转换不保留元数据,要读元数据必须对原图调用
.Meta。
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 页面上的图还是原图大小,处理像没生效 | 输出用了源对象的地址,而不是方法返回的新对象 | 把 .Resize/.Fill 的结果赋给变量或放进 with,用它的 .RelPermalink |
| 没报错但结果不对 | 处理后的图片 404 | 按「源图名 + 尺寸」猜文件名;实际名字带哈希且随规格变化 | 一律用模板返回的 .RelPermalink,不要手写处理结果的路径 |
| 没报错但结果不对 | Processed images 一直是 0 |
图片不是可处理资源(例如把占位文本当成图片文件),或模板根本没调用处理方法 | 用 reflect.IsImageResourceProcessable 自查;确认模板真的调用了处理方法 |
| 报错看不懂 | failed to load image config: … invalid format: invalid checksum |
文件扩展名说是图片,内容却不是合法图片 | 换一张真实图片;确认资源文件没有被截断或写错编码 |
| 报错看不懂 | 模板里 nil pointer evaluating 出现在 .Width、.RelPermalink |
资源没取到就继续链式取值 | 用 with 包一层,或先 errorf 显式报错 |
| 没报错但结果不对 | 构建一次比一次慢、磁盘占用增大 | 改了处理方法或删了图片后,缓存里留下不再使用的处理结果 | 构建时加 hugo build --gc 做垃圾回收 |
| 没报错但结果不对 | 转成 JPEG 后透明区域变成奇怪的颜色 | 透明格式转不支持透明的格式时用 [imaging] bgColor 填充 |
设置合适的 bgColor(默认 #ffffff) |
| 没报错但结果不对 | 缩放后画质明显变差或锯齿 | resampleFilter 用了 box(默认,快但画质一般) |
换成 lanczos、catmullRom 等,代价是构建变慢 |
更多排查入口见故障排查。
性能:缓存、回收与资源占用
Hugo 按需处理图像并把结果缓存到项目配置中文件缓存(file cache)指定的目录。若站点部署在 Netlify,可在配置中加入以下内容,让缓存在两次构建之间保留:
[caches]
[caches.images]
dir = ':cacheDir/images'改动处理方法,或重命名、删除图片后,缓存里会留下不再使用的文件,可运行垃圾回收(garbage collection)清理并回收磁盘空间:
hugo build --gc处理图像所需的时间与内存随图像尺寸增长,一张 4032x2268 的图片远比 1920x1080 的图片昂贵。若源图远大于实际发布尺寸,建议在构建之前先把它们缩小。
配置成像行为
站点级的默认行为写在项目配置的 [imaging] 区段中,该区段适用于所有图像格式,可参考配置 Hugo:
[imaging]
anchor = 'smart'
bgColor = '#ffffff'
resampleFilter = 'box'
[imaging.avif]
compression = 'lossy'
encoderSpeed = 10
hint = 'photo'
quality = 60
[imaging.jpeg]
quality = 75
[imaging.webp]
compression = 'lossy'
hint = 'photo'
method = 2
quality = 75
useSharpYuv = false顶层设置的含义:
anchor:裁剪或填充时使用的焦点,可取TopLeft、Top、TopRight、Left、Center、Right、BottomLeft、Bottom、BottomRight或Smart,默认smart,大小写不敏感;smart借助muesli/smartcrop找出图像中最值得保留的区域。bgColor:把透明图像转换为不支持透明的格式(例如 PNG 转 JPEG)时填充的背景色,同时也是非正交旋转时空白区域的填充色,取值须为 RGB 十六进制颜色,默认#ffffff。resampleFilter:缩放、适配或填充时计算新像素所用的算法,常用box(默认)、lanczos、catmullRom、mitchellNetravali、linear、nearestNeighbor;追求画质可以逐一试换,代价是构建变慢。
顶层的 quality、compression、hint 三个键自 Hugo 0.163.0 起弃用,请改用各格式子区段中的同名键。AVIF 与 WebP 支持 lossy、lossless 两种 compression;quality 取 1 到 100 的整数,AVIF 默认 60、JPEG 与 WebP 默认 75,且不同格式的取值不可直接比较。WebP 的 method 取 0 到 6(默认 2),数值越大压缩效率与画质越好;useSharpYuv 默认 false,开启后优先保证锐度。
元数据的提取与过滤由 [imaging.meta] 控制:fields 用通配切片(glob slice)匹配需要保留的字段,默认排除 ColorSpace、Exif、GPS、Resolution、WhiteBalance 等技术字段,写成 ['**'] 可全部保留;sources 指定元数据来源,可取 exif、iptc、xmp,默认只取前两者。
生成响应式图片
把同一张图片按多个宽度分别处理,再写进 srcset,浏览器就会按视口大小自行选择合适的版本。先在各宽度上处理一次并保存结果,避免在模板里重复处理:
{{ with .Resources.GetMatch "cover.jpg" }}
{{ $small := .Resize "480x" }}
{{ $medium := .Resize "960x" }}
{{ $large := .Resize "1440x" }}
<img
src="{{ $large.RelPermalink }}"
srcset="{{ $small.RelPermalink }} 480w,
{{ $medium.RelPermalink }} 960w,
{{ $large.RelPermalink }} 1440w"
sizes="(max-width: 600px) 480px, 960px"
width="{{ $large.Width }}"
height="{{ $large.Height }}"
alt="封面">
{{ end }}首次构建会真正生成这些图片,之后的构建直接复用资源缓存,因此处理成本只付出一次。Markdown 正文中插入的图片,可以交给渲染钩子统一套用同样的处理逻辑。