Hugo中[imaging]参数对页面捆绑图片无效？求助排查

问题核心 #

[imaging]配置本身有效，但它仅对Hugo资源管道主动处理的图片生效。你当前的图片被归类为「Non-page files」直接复制，是因为没有通过Hugo的资源引用语法触发处理流程，原生Markdown图片引用不会触发压缩。

为什么页面捆绑的图片没被处理 #

• Hugo默认不会自动处理页面捆绑（Page Bundle）中的静态文件，只有当你通过主题短代码或Hugo资源函数调用图片时，才会启动资源处理管道，应用[imaging]的压缩配置。
• 若直接用![alt](my-image.jpg)这种原生Markdown语法引用图片，Hugo会将其视为普通静态资源，直接复制到public目录，完全跳过压缩逻辑。

解决方法 #

方法1：使用主题内置短代码（推荐，针对PaperMod） #

PaperMod主题内置了img短代码，可直接替换Markdown中的图片引用：

{{< img src="my-image.jpg" alt="你的图片描述" >}}

这样会自动触发Hugo的资源处理，应用[imaging]中的质量、滤镜等配置。

方法2：手动通过资源函数处理 #

如果需要自定义处理逻辑，可在模板或自定义短代码中使用Hugo资源函数：

{{ with .Page.Resources.Get "my-image.jpg" }}
  {{ $processed := .Resize "800x" }} <!-- 尺寸可自定义，质量会继承[imaging]的配置 -->
  <img src="{{ $processed.RelPermalink }}" alt="图片描述">
{{ end }}

也可以在Resize中直接指定质量（覆盖全局配置）：

{{ $processed := .Resize "800x q1" }}

验证处理效果 #

修改后重新执行hugo构建，日志中的Processed images会显示处理的图片数量，同时public目录中的图片会是压缩后的版本。

内容的提问来源于stack exchange，提问作者Hugo REYMOND