图片处理

图片资源

处理图片需要将其作为页面资源、全局资源或远程资源访问。

页面资源

页面资源是位于页面包中的文件。页面包是一个目录，其根目录下包含一个 index.md 或 _index.md 文件。

content/
└── posts/
    └── post-1/           <-- 页面包
        ├── index.md
        └── sunset.jpg    <-- 页面资源

要访问页面资源中的图片：

{{ $image := .Resources.Get "sunset.jpg" }}

全局资源

全局资源是 assets 目录中或已挂载到 assets 目录的任何目录中的文件。

assets/
└── images/
    └── sunset.jpg    <-- 全局资源

要访问全局资源中的图片：

{{ $image := resources.Get "images/sunset.jpg" }}

远程资源

远程资源是远程服务器上的文件，可以通过 HTTP 或 HTTPS 访问。要访问远程资源中的图片：

{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}

图片渲染

一旦您已将图片作为资源访问，即可使用 Permalink 、 RelPermalink 、 Width 和 Height 属性在模板中渲染它。

示例 1：如果找不到资源，则抛出错误。

{{ $image := .Resources.GetMatch "sunset.jpg" }}
<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">

示例 2：如果找不到资源，则跳过图片渲染。

{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ with $image }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

示例 3：一种更简洁的方法来跳过找不到资源时的图片渲染。

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

示例 4：如果访问远程资源时出现问题，则跳过渲染。

{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
{{ with resources.GetRemote $u }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ else }}
  {{ errorf "无法获取远程资源 %q" $u }}
{{ end }}

图片处理方法

image 资源实现了 Process 、 Resize 、 Fit 、 Fill 、 Crop 、 Filter 、 Colors 和 Exif 方法。

Process

New in v0.119.0

Process 使用给定的规范处理图像。规范可以包含一个可选操作，即 resize 、 crop 、 fit 或 fill 之一。这意味着您可以使用此方法代替 Resize 、 Fit 、 Fill 或 Crop 。

有关可用选项，请参阅选项。

您还可以使用此方法应用不需要任何缩放的图像处理，例如格式转换：

{{/* 将图像从 JPG 转换为 PNG。 */}}
{{ $png := $jpg.Process "png" }}

更多示例：

{{/* 将图像逆时针旋转 90 度。 */}}
{{ $image := $image.Process "r90" }}

{{/* 缩放操作。 */}}
{{ $image := $image.Process "resize 600x" }}
{{ $image := $image.Process "crop 600x400" }}
{{ $image := $image.Process "fit 600x400" }}
{{ $image := $image.Process "fill 600x400" }}

Resize

将图像调整为给定的宽度和/或高度。

如果您同时指定宽度和高度，除非原始图像具有相同的纵横比，否则生成的图像将被不成比例地缩放。

{{/* 将大小调整为 600px 宽并保持纵横比 */}}
{{ $image := $image.Resize "600x" }}

{{/* 将大小调整为 400px 高并保持纵横比 */}}
{{ $image := $image.Resize "x400" }}

{{/* 将大小调整为 600px 宽和 400px 高 */}}
{{ $image := $image.Resize "600x400" }}

Fit

缩小图像以适应给定的尺寸，同时保持纵横比。您必须同时提供宽度和高度。

{{ $image := $image.Fit "600x400" }}

Fill

裁剪和调整图像大小以匹配给定的尺寸。您必须同时提供宽度和高度。使用 anchor 选项更改裁剪框锚点。

{{ $image := $image.Fill "600x400" }}

Crop

裁剪图像以匹配给定的尺寸，而不调整大小。您必须同时提供宽度和高度。使用 anchor 选项更改裁剪框锚点。

{{ $image := $image.Crop "600x400" }}

Filter

将一个或多个过滤器应用于图像。

{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

使用管道以更函数化的风格编写。Hugo 按给定的顺序应用过滤器。

{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

有时，先创建一个过滤器链然后重用它会很有用。

{{ $filters := slice  (images.GaussianBlur 6) (images.Pixelate 8) }}
{{ $image1 := $image1.Filter $filters }}
{{ $image2 := $image2.Filter $filters }}

Colors

.Colors 使用简单的直方图方法返回图像中主要颜色的十六进制字符串切片。

{{ $colors := $image.Colors }}

此方法速度很快，但是如果您还缩小图像，则最好从缩小后的图像中提取颜色以提高性能。

EXIF

提供包含图像元数据的 EXIF 对象。

您可以在 JPEG、PNG、TIFF 和 WebP 图像中访问 EXIF 数据。为了防止处理没有 EXIF 数据的图像时出错，请将访问内容包装在 with 语句中。

{{ with $image.Exif }}
  日期: {{ .Date }}
  经纬度: {{ .Lat }}/{{ .Long }}
  标签:
  {{ range $k, $v := .Tags }}
    标签: {{ $k }}: {{ $v }}
  {{ end }}
{{ end }}

您还可以使用 lang.FormatNumber 函数单独访问 EXIF 字段，并根据需要格式化这些字段。

{{ with $image.Exif }}
  <ul>
    {{ with .Date }}<li>日期: {{ .Format "January 02, 2006" }}</li>{{ end }}
    {{ with .Tags.ApertureValue }}<li>光圈: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.BrightnessValue }}<li>亮度: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.ExposureTime }}<li>曝光时间: {{ . }}</li>{{ end }}
    {{ with .Tags.FNumber }}<li>F 值: {{ . }}</li>{{ end }}
    {{ with .Tags.FocalLength }}<li>焦距: {{ . }}</li>{{ end }}
    {{ with .Tags.ISOSpeedRatings }}<li>ISO 感光度: {{ . }}</li>{{ end }}
    {{ with .Tags.LensModel }}<li>镜头型号: {{ . }}</li>{{ end }}
  </ul>
{{ end }}

EXIF 方法

日期: (time.Time) 返回图像创建日期/时间。使用[time.Format]函数进行格式化。

纬度: (float64) 以度为单位返回 GPS 纬度。
经度: (float64) 以度为单位返回 GPS 经度。
标签: (exif.Tags) 返回此图像的可用 EXIF 标签的集合。您可以在站点配置中包含或排除此集合中的特定标签。

图片处理选项

Resize 、 Fit 、 Fill 和 Crop 方法接受以空格分隔的、不区分大小写的选项列表。列表中选项的顺序无关紧要。

尺寸

使用 Resize 方法，您必须指定宽度、高度或两者兼有。 Fit 、 Fill 和 Crop 方法需要宽度和高度。所有尺寸均以像素为单位。

{{ $image := $image.Resize "600x" }}
{{ $image := $image.Resize "x400" }}
{{ $image := $image.Resize "600x400" }}
{{ $image := $image.Fit "600x400" }}
{{ $image := $image.Fill "600x400" }}
{{ $image := $image.Crop "600x400" }}

旋转

将图像逆时针旋转给定的角度。Hugo 在缩放之前执行旋转。例如，如果原始图像为 600x400，并且您希望将图像逆时针旋转 90 度，同时将其缩放 50%：

{{ $image = $image.Resize "200x r90" }}

在上面的示例中，宽度表示旋转后的所需宽度。

要旋转图像而不缩放，请使用原始图像的尺寸：

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d r90" .Height .Width) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

在上面的示例中，第二行中，我们反转了宽度和高度以反映旋转后的所需尺寸。

锚点

使用 Crop 或 Fill 方法时，锚点决定裁剪框的位置。您可以指定 TopLeft 、 Top 、 TopRight 、 Left 、 Center 、 Right 、 BottomLeft 、 Bottom 、 BottomRight 或 Smart 。

默认值为 Smart ，它使用 Smartcrop 图像分析来确定裁剪框的最佳位置。您可以在站点配置中覆盖默认值。

例如，如果您有一个 400x200 的图像，其中左上角象限有一只鸟，您可以创建一个包含这只鸟的 200x100 的缩略图：

{{ $image.Crop "200x100 TopLeft" }}

如果您在使用 Crop 或 Fill 方法时应用旋转，请相对于旋转后的图像指定锚点。

目标格式

默认情况下，Hugo 以源格式编码图像。您可以通过指定 bmp 、 gif 、 jpeg 、 jpg 、 png 、 tif 、 tiff 或 webp 来将图像转换为另一种格式。

{{ $image.Resize "600x webp" }}

要转换图像而不缩放，请使用原始图像的尺寸：

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d webp" .Width .Height) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

质量

适用于 JPEG 和 WebP 图像， q 值决定转换后图像的质量。较高的值会产生质量更好的图像，而较低的值会产生较小的文件。将此值设置为 1 到 100（含）之间的整数。

默认值为 75。您可以在站点配置中覆盖默认值。

{{ $image.Resize "600x webp q50" }}

提示

适用于 WebP 图片，此选项对应于一组预定义的编码参数，等同于 cwebp 编码器的 -preset 标志。

值	示例
`drawing`	具有高对比度细节的手绘图或线条图
`icon`	小型彩色图像
`photo`	具有自然光照的户外照片
`picture`	室内照片，例如肖像
`text`	主要为文本的图像

默认值为 photo 。您可以在站点配置中覆盖默认值。

{{ $image.Resize "600x webp picture" }}

背景颜色

当将图像从支持透明度的格式（例如，PNG）转换为不支持透明度的格式（例如，JPEG）时，您可以指定结果图像的背景颜色。

使用 3 位或 6 位十六进制颜色代码（例如， #00f 或 #0000ff ）。

默认值为 #ffffff （白色）。您可以在站点配置中覆盖默认值。

{{ $image.Resize "600x jpg #b31280" }}

重采样过滤器

您可以指定调整图像大小时使用的重采样过滤器。常用的重采样过滤器包括：

过滤器	描述
`Box`	适用于缩小尺寸的简单快速的平均过滤器
`Lanczos`	用于摄影图像的高质量重采样过滤器，产生清晰的结果
`CatmullRom`	锐利的三次过滤器，比 Lanczos 过滤器更快，同时提供类似的结果
`MitchellNetravali`	三次过滤器，产生更平滑的结果，比 CatmullRom 具有更少的振铃伪影
`Linear`	双线性重采样过滤器，产生平滑的输出，比三次过滤器快
`NearestNeighbor`	最快的重采样过滤器，没有抗锯齿

默认值为 Box 。您可以在站点配置中覆盖默认值。

{{ $image.Resize "600x400 Lanczos" }}

有关完整的重采样过滤器列表，请参阅 github.com/disintegration/imaging 。如果您希望以牺牲性能为代价来提高图像质量，您可能需要尝试其他过滤器。

图片处理示例

以下示例中使用的日落照片版权归 Bjørn Erik Pedersen 所有（知识共享署名-相同方式共享 4.0 国际许可证）

fit 90x90

这是用于生成上述示例的简码：

{{- /*
Renders the given image using the given process specification.

@param {string} (positional parameter 0) The path to the image, relative to the current page. The image must be a page resource.
@param {string}} (positional parameter 1) The image processing specification.

@returns template.HTML

@example {{< imgproc "sunset.jpg" "resize 300x" />}}
*/}}

{{- with $.Get 0 }}
  {{- with $i := $.Page.Resources.Get . }}
    {{- with $spec := $.Get 1 }}
      {{- with $i.Process . }}
        <figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc">
          <img style="max-width: 100%; width: auto; height: auto;" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
          <figcaption>
            <small>
              {{- with $.Inner }}
                {{ . }}
              {{- else }}
                {{ $spec }}
              {{- end }}
            </small>
          </figcaption>
        </figure>
      {{- end }}
    {{- else }}
      {{- errorf "The %q shortcode requires a positional parameter (1) containing the image processing specification. See %s" $.Name $.Position }}
    {{- end }}
  {{- else }}
    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
  {{- end }}
{{- else }}
  {{- errorf "The %q shortcode requires a positional parameter (0) indicating the image path, relative to the current page. See %s" $.Name $.Position }}
{{- end }}

像这样从您的 Markdown 调用简码：

{{< imgproc "sunset.jpg" "resize 300x" />}}

图像配置

处理选项

在您的站点配置中定义一个 imaging 部分以设置默认的图像处理选项。

hugo.

imaging:
  bgColor: '#ffffff'
  hint: photo
  quality: 75
  resampleFilter: box

[imaging]
  bgColor = '#ffffff'
  hint = 'photo'
  quality = 75
  resampleFilter = 'box'

{
   "imaging": {
      "bgColor": "#ffffff",
      "hint": "photo",
      "quality": 75,
      "resampleFilter": "box"
   }
}

锚点: 请参阅图像处理选项：锚点。
bgColor: 请参阅图像处理选项：背景颜色。
提示: 请参阅图像处理选项：提示。
质量: 请参阅图像处理选项：质量。
重采样过滤器: 请参阅图像处理选项：重采样过滤器。

EXIF 数据

在您的站点配置中定义一个 imaging.exif 部分以控制 EXIF 数据的可用性。

hugo.

imaging:
  exif:
    disableDate: false
    disableLatLong: false
    excludeFields: ""
    includeFields: ""

[imaging]
  [imaging.exif]
    disableDate = false
    disableLatLong = false
    excludeFields = ''
    includeFields = ''

{
   "imaging": {
      "exif": {
         "disableDate": false,
         "disableLatLong": false,
         "excludeFields": "",
         "includeFields": ""
      }
   }
}

disableDate: Hugo 将图像创建日期/时间提取到 .Date 中。设置为 true 以禁用。默认为 false 。
disableLatLong: Hugo 将 GPS 纬度和经度提取到 .Lat 和 .Long 中。设置为 true 以禁用。默认为 false 。
excludeFields: 与要从 .Tags 集合中排除的 EXIF 标签匹配的正则表达式。默认为 “"。
includeFields: 与要包含在 .Tags 集合中的 EXIF 标签匹配的正则表达式。默认为 “"。要包含所有可用标签，请将此值设置为 “.*"。

图像的智能裁剪

默认情况下，Hugo 在使用 Crop 或 Fill 方法裁剪图像时使用 Smartcrop 库。您可以手动设置锚点，但在大多数情况下， Smart 选项将是一个不错的选择。

使用上面日落图像的示例：

图片处理性能注意事项

Hugo 将处理后的图像缓存到 resources 目录中。如果您将此目录包含在源代码控制中，Hugo 将不必在 CI/CD 工作流程（例如，GitHub Pages、GitLab Pages、Netlify 等）中重新生成图像。这将加快构建速度。

如果您更改了图像处理方法或选项，或者重命名或删除了图像，则 resources 目录将包含未使用的图像。要删除未使用的图像，请使用以下命令执行垃圾回收：

hugo --gc

图片资源

页面资源

全局资源

远程资源

图片渲染

图片处理方法

Process

Resize

Fit

Fill

Crop

Filter

Colors

EXIF

EXIF 方法

图片处理选项

尺寸

旋转

锚点

目标格式

质量

提示

背景颜色

重采样过滤器

图片处理示例

图像配置

处理选项

EXIF 数据

图像的智能裁剪

图片处理性能注意事项

See also

Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)