HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
CONTENT MANAGEMENT FUNDAMENTALS

图片处理

调整大小、裁剪、旋转、过滤和转换图像。

图片资源

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

页面资源

页面资源是位于 页面包 中的文件。页面包是一个目录,其根目录下包含一个 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 方法。

在图像转换过程中不会保留元数据(EXIF、IPTC、XMP 等)。使用原始图像的 Exif 方法从 JPEG、PNG、TIFF 和 WebP 图像中提取 EXIF 元数据。

Process

New in v0.119.0

Process 方法也可以用作过滤器,如果您需要将多个过滤器应用于图像,则此方法更有效。请参阅 Process 过滤器 。

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 国际许可证)

resize 300x
fill 90x120 left
fill 90x120 right
fit 90x90
crop 250x250 center
resize 300x q10

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

{{- /*
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" />}}

请注意上面的自闭合简码语法。您可以使用或不使用 内部内容 来调用 imgproc 简码。

图像配置

处理选项

在您的站点配置中定义一个 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 排除了以下标签: ColorSpace 、 Contrast 、 Exif 、 Exposure[M|P|B] 、 Flash 、 GPS 、 JPEG 、 Metering 、 Resolution 、 Saturation 、 Sensing 、 Sharp 和 WhiteBalance 。

要控制标签的可用性,请按照上述说明更改 excludeFields 或 includeFields 设置。

图像的智能裁剪

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

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

fill 200x200 smart
crop 200x200 smart

图片处理性能注意事项

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

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

hugo --gc

See also

  • transform.Unmarshal
  • 名称
  • 术语表
  • 标题
  • 组织

On this page

  • 图片资源
  • 图片渲染
  • 图片处理方法
  • 图片处理选项
  • 图片处理示例
  • 图像配置
  • 图像的智能裁剪
  • 图片处理性能注意事项
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护