内容管理

图像处理

图像资源处理方法、成像配置与响应式图片生成;含输出文件名规则、验证方法与常见坑。

难度
进阶
预计用时
25–35 分钟

开始之前,你需要

  • 读过页面资源,知道 .Resources 与 resources.Get 的区别。
  • 站点里至少有一张真实图片可以拿来试(不是占位文本文件)。

读完之后你能

  • 把图片捕获为页面资源、全局资源或远程资源,并用 .Resize / .Fill / .Process 等生成新图片;
  • 在产物目录里认出处理后的图片文件名,用构建统计确认处理确实发生了;
  • 用 [imaging] 配置统一各格式的质量与缩放算法;
  • 用一次处理 + srcset 生成响应式图片,避免在模板里重复处理。

接着读:页面资源 · Resource · 图片

这一页解决什么问题

Hugo 可以在构建过程中转换与分析图像。任何图片格式都能作为资源管理,但只有可处理的图像(processable image)才能用下文的方法转换;处理结果会写入缓存,以保证后续构建依旧很快。判断一张图片能否处理,用 reflect.IsImageResourceProcessable 函数。

图像处理的坑几乎都不在「方法怎么调」,而在结果去了哪里:处理后的图片是新文件、名字带哈希,和源图不在同一个名字上。本页给出一条能自己验的路径:

  1. 先捕获资源(页面资源 / 全局资源 / 远程资源);
  2. 再调用方法,拿到一个新的资源对象;
  3. 用新对象的 .RelPermalink 输出——直接用源图地址是看不到处理结果的。

验证图像处理是否发生,两步:

bash
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。

还可以先在模板里自查可处理性:

go-html-template
{{ reflect.IsImageResourceProcessable (resources.Get "images/a.png") }}

你应当看到什么:输出 true 才说明这张图能转换。若为 false,后面所有 .Resize 一类调用都没有意义。

图像处理概览

Hugo 可以在构建过程中转换与分析图像。任何图片格式都能作为资源管理,但只有可处理的图像(processable image)才能用下文的方法转换;处理结果会写入缓存,以保证后续构建依旧很快。判断一张图片能否处理,用 reflect.IsImageResourceProcessable 函数。

捕获三种图像资源

要处理图像,先把它捕获为页面资源(page resource)、全局资源(global resource)或远程资源(remote resource)。

页面资源是与叶子包 index.md 放在同一目录的图片,用页面对象的 .Resources 取得:

go-html-template
{{ $image := .Resources.Get "sunset.jpg" }}

全局资源放在项目的 assets 目录中,用 resources.Get 取得:

go-html-template
{{ $image := resources.Get "images/sunset.jpg" }}

远程资源用 resources.GetRemote 按 URL 取得:

go-html-template
{{ $image := resources.GetRemote "https://example.org/images/sunset.jpg" }}

相关概念见页面资源。

渲染图像

捕获资源后,用 .Permalink、.RelPermalink、.Width、.Height 等方法把图片写进模板。资源不存在时,可以直接抛错,也可以用 with 跳过渲染:

go-html-template
{{ with .Resources.GetMatch "sunset.jpg" }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}

远程资源还可能取回失败,可用 try 区分错误与结果:

go-html-template
{{ $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 按需生成处理结果、写入缓存并返回一个新的资源对象:

go-html-template
{{ 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,可在配置中加入以下内容,让缓存在两次构建之间保留:

toml
[caches]
  [caches.images]
    dir = ':cacheDir/images'

改动处理方法,或重命名、删除图片后,缓存里会留下不再使用的文件,可运行垃圾回收(garbage collection)清理并回收磁盘空间:

bash
hugo build --gc

处理图像所需的时间与内存随图像尺寸增长,一张 4032x2268 的图片远比 1920x1080 的图片昂贵。若源图远大于实际发布尺寸,建议在构建之前先把它们缩小。

配置成像行为

站点级的默认行为写在项目配置的 [imaging] 区段中,该区段适用于所有图像格式,可参考配置 Hugo:

toml
[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,浏览器就会按视口大小自行选择合适的版本。先在各宽度上处理一次并保存结果,避免在模板里重复处理:

go-html-template
{{ 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 正文中插入的图片,可以交给渲染钩子统一套用同样的处理逻辑。

相关主题