图像函数 on Hugo 中文文档

images.AutoOrient

Fri, 02 Oct 2026 00:00:00 +0800

用法

创建滤镜：

{{ $filter := images.AutoOrient }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

images.Brightness

Fri, 02 Oct 2026 00:00:00 +0800

百分比的取值范围是 [-100, 100]，其中 0 表示不产生任何效果。取值 -100 得到纯黑图像，取值 100 得到纯白图像。

用法

创建图像滤镜：

{{ $filter := images.Brightness 12 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.ColorBalance

Fri, 02 Oct 2026 00:00:00 +0800

每个通道（红、绿、蓝）的百分比取值范围是 [-100, 500]。

用法

创建滤镜：

{{ $filter := images.ColorBalance -10 10 50 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.Colorize

Fri, 02 Oct 2026 00:00:00 +0800

色相是色轮上的角度，取值范围通常是 [0, 360]。

饱和度必须在 [0, 100] 区间内。

百分比指定效果的强度，必须在 [0, 100] 区间内。

用法

创建滤镜：

{{ $filter := images.Colorize 180 50 20 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.Config

Fri, 02 Oct 2026 00:00:00 +0800

{{ $ic := images.Config "/static/images/a.jpg" }}

{{ $ic.Width }} → 600 (int)
{{ $ic.Height }} → 400 (int)

支持的图像格式包括 AVIF、BMP、GIF、HEIC、HEIF、JPEG、PNG、TIFF 和 WebP。

images.Contrast

Fri, 02 Oct 2026 00:00:00 +0800

百分比的取值范围是 [-100, 100]，其中 0 表示不产生任何效果。取值 -100 得到纯灰图像，取值 100 则会得到对比度过高的图像。

用法

创建滤镜：

{{ $filter := images.Contrast -20 }}

用 images.Filter 函数应用该滤镜：

images.Dither

Fri, 02 Oct 2026 00:00:00 +0800

选项

images.Dither 滤镜接受一个选项映射（map）。

colors: （[]string）构成抖动调色板的两种或更多颜色组成的切片，每种颜色用 RGB 或 RGBA 的十六进制值表示，可以带或不带前导井号。默认值是不透明黑（000000ff）和不透明白（ffffffff）。
method: （string）抖动方法。可用方法见下文抖动方法一节。默认为 FloydSteinberg。
serpentine: （bool）仅适用于误差扩散类抖动方法：是否以蛇形（serpentine）方式应用误差扩散矩阵，即每隔一行改为从右到左。这能大幅减少线状伪影。默认为 true。
strength: （float）应用抖动矩阵的强度，通常取值在 [0, 1] 区间内。取值 1.0 表示以 100% 强度应用抖动矩阵（不修改抖动矩阵）。strength 与对比度成反比：降低强度会提高对比度。把 strength 设为 0.8 之类的值有助于减少抖动图像中的噪点。默认为 1.0。

用法

创建选项映射：

images.Filter

Fri, 02 Oct 2026 00:00:00 +0800

images.Filter 函数对一个可处理的图像应用一个或多个图像滤镜后返回一个新的资源。

用法

用 images.Filter 函数应用模糊、锐化、灰度转换等效果。可以传入单个滤镜，也可以传入滤镜切片。传入切片时，Hugo 从左到右依次应用这些滤镜。

images.Gamma

Fri, 02 Oct 2026 00:00:00 +0800

伽马值必须为正数。大于 1 的值会让图像变亮，小于 1 的值会让图像变暗。伽马值为 1 时该滤镜不产生任何效果。

用法

创建滤镜：

{{ $filter := images.Gamma 1.667 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.GaussianBlur

Fri, 02 Oct 2026 00:00:00 +0800

sigma 值必须为正数，它表示图像被模糊的程度。受模糊影响的半径约为 sigma 值的 3 倍。

用法

创建滤镜：

{{ $filter := images.GaussianBlur 5 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.Grayscale

Fri, 02 Oct 2026 00:00:00 +0800

用法

创建滤镜：

{{ $filter := images.Grayscale }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

示例

英文原文此处用示例照片演示 Grayscale 滤镜的前后对比效果；本站未收录该示例图。

images.Hue

Fri, 02 Oct 2026 00:00:00 +0800

色相角度的偏移量通常在 [-180, 180] 区间内，其中 0 表示不产生任何效果。

用法

创建滤镜：

{{ $filter := images.Hue -15 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.Invert

Fri, 02 Oct 2026 00:00:00 +0800

用法

创建滤镜：

{{ $filter := images.Invert }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

示例

英文原文此处用示例照片演示 Invert 滤镜的前后对比效果；本站未收录该示例图。

images.Mask

Fri, 02 Oct 2026 00:00:00 +0800

（0.141.0 新增）

images.Mask 滤镜对图像应用遮罩。遮罩中的黑色像素使基础图像对应区域变为透明，白色像素则保持不透明。彩色图像会先转换为灰度再用于遮罩。遮罩会自动缩放以匹配基础图像的尺寸。

images.Opacity

Fri, 02 Oct 2026 00:00:00 +0800

不透明度（opacity）的取值范围是 [0, 1]。取值 0 得到完全透明的图像，取值 1 得到完全不透明的图像（没有透明度）。

用法

创建滤镜：

{{ $filter := images.Opacity 0.65 }}

用 images.Filter 函数应用该滤镜：

images.Overlay

Fri, 02 Oct 2026 00:00:00 +0800

用法

把叠加图像捕获为资源：

{{ $overlay := "" }}
{{ $path := "images/logo.png" }}
{{ with resources.Get $path }}
  {{ $overlay = . }}
{{ else }}
  {{ errorf "Unable to get resource %q" $path }}
{{ end }}

叠加图像可以是全局资源、页面资源或远程资源。

创建滤镜：

{{ $filter := images.Overlay $overlay 20 20 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.Padding

Fri, 02 Oct 2026 00:00:00 +0800

最后一个参数是画布颜色，用 RGB 或 RGBA 十六进制颜色表示。默认值为 ffffffff（不透明白）。它前面的参数是内边距（padding）值，单位为像素，采用 CSS 简写属性语法。内边距取负值会裁剪图像。

用法

创建滤镜：

{{ $filter := images.Padding 20 40 "#976941" }}

用 images.Filter 函数应用该滤镜：

images.Pixelate

Fri, 02 Oct 2026 00:00:00 +0800

用法

创建滤镜：

{{ $filter := images.Pixelate 4 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

示例

英文原文此处用示例照片演示 Pixelate 4 的前后对比效果；本站未收录该示例图。

images.Process

Fri, 02 Oct 2026 00:00:00 +0800

返回一个按给定处理规格处理图像的图像滤镜。这个通用滤镜支持完整的图像变换，包括缩放、裁剪、旋转和格式转换，全部写在一条规格字符串中。它可以作为 Filter 方法或 images.Filter 函数的参数。

{{ with resources.Get "images/original.jpg" }}
  {{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

上面的示例中，"crop 200x200 TopRight webp q50" 就是处理规格。

处理规格

处理规格是一个以空格分隔、大小写不敏感的列表，包含下列选项中的一个或多个，顺序任意：

images.QR

Fri, 02 Oct 2026 00:00:00 +0800

（0.141.0 新增）

images.QR 函数按指定选项把给定文本编码为二维码，返回一个图像资源。生成图像的尺寸取决于三个因素：

数据长度：文本越长，为容纳更大的信息密度就需要越大的图像。
纠错级别：纠错级别越高，二维码抗损毁能力越强，但通常需要略大的图像尺寸来保持可读性。
每模块像素数：分配给每个模块（二维码的最小单元）的图像像素数会直接影响整体图像尺寸。每模块像素数越多，图像越大、分辨率越高。

虽然默认选项值对多数场景已经够用，仍应在屏幕显示和打印两种情况下都测试渲染出的二维码。

images.Saturation

Fri, 02 Oct 2026 00:00:00 +0800

百分比的取值范围是 [-100, 500]，其中 0 表示不产生任何效果。

用法

创建滤镜：

{{ $filter := images.Saturation 65 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.Sepia

Fri, 02 Oct 2026 00:00:00 +0800

百分比的取值范围是 [0, 100]，其中 0 表示不产生任何效果。

用法

创建滤镜：

{{ $filter := images.Sepia 75 }}

用 images.Filter 函数应用该滤镜：

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

也可以在 Resource 对象上调用 Filter 方法应用该滤镜：

images.Sigmoid

Fri, 02 Oct 2026 00:00:00 +0800

这是一种非线性对比度调整，适合用于照片修饰；它保留了高光和阴影的细节。

midpoint 是对比度的中点，必须在 [0, 1] 区间内，通常取 0.5。

factor 表示提高或降低对比度的程度，通常在 [-10, 10] 区间内，其中 0 表示不产生任何效果。正值提高对比度，负值降低对比度。

images.Text

Fri, 02 Oct 2026 00:00:00 +0800

选项

images.Text 滤镜接受一个选项映射（map）。

虽然这些选项都不是必填的，但至少应把 size 设为图像高度的某个合理比例。

alignx: （0.141.0 新增） （string）文字相对于水平偏移量的水平对齐方式，取 left、center 或 right 之一。默认为 left。
aligny: （0.147.0 新增） （string）文字相对于垂直偏移量的垂直对齐方式，取 top、center 或 bottom 之一。默认为 top。
color: （string）字体颜色，可以是 3 位或 6 位十六进制颜色码。默认为 #ffffff（白色）。
font: （resource.Resource）字体可以是全局资源、页面资源或远程资源。默认是 Go Regular，一种比例式无衬线 TrueType 字体。
linespacing: （int）每行之间的像素数。若行高为 1.4，把 linespacing 设为 size 的 0.4 倍。默认为 2。
size: （int）以像素为单位的字号。默认为 20。
x: （int）相对于图像左边缘的水平偏移量，单位为像素。默认为 10。
y: （int）相对于图像上边缘的垂直偏移量，单位为像素。默认为 10。

用法

设置文本和路径：

images.UnsharpMask

Fri, 02 Oct 2026 00:00:00 +0800

sigma 参数用于高斯函数，影响作用半径。sigma 必须为正数。锐化半径约为 sigma 值的 3 倍。

amount 参数控制边缘边界变暗和变亮的程度，通常在 0.5 到 1.5 之间。

threshold 参数控制会被锐化的最小亮度变化，通常在 0 到 0.05 之间。