在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

gohugoio/hugo

菜单

资源管理

相关源文件

目的与范围

本文档描述了 Hugo 的资源管理系统，该系统处理图像、CSS、JavaScript 和其他文件等各种类型的资源。资源管理系统提供了统一的接口来加载、转换和发布这些资源。

该系统支持以下关键功能：

  • 从不同来源加载资源（页面包、全局资源、远程 URL）
  • 转换资源（图像处理、最小化、指纹识别等）
  • 缓存转换后的资源以提高性能
  • 将资源发布到输出目录

有关特定图像处理功能的信息，请参阅 图像处理。

资源类型和架构

资源管理系统建立在处理不同类型资源的接口和实现的分层结构之上。

资源类型层级

来源：resources/resource/resourcetypes.go71-156 resources/resource.go42-56 resources/image.go49-54

关键资源接口

接口描述
resource.Resource所有资源的基础接口
resource.ContentResource可以访问内容的资源
resource.ReadSeekCloserResource可以读取的资源
images.ImageResource图像资源的专用接口

关键资源实现

实现描述
resources.genericResource大多数资源的通用实现
resources.imageResource图像资源的实现
resources.resourceAdapter资源转换的适配器

资源加载和创建

tpl/resources 包提供了几种加载或创建资源的方法。

资源来源

来源：resources/resource_factories/create/create.go45-121 tpl/resources/resources.go90-145 tpl/resources/resources.go234-245

加载方法

方法描述示例
.Resources.Get从页面包中获取资源{{ $image := .Resources.Get "image.jpg" }}
.Resources.Match从页面包中获取匹配的资源{{ $images := .Resources.Match "images/*.jpg" }}
resources.Get从 assets 目录获取全局资源{{ $css := resources.Get "css/styles.css" }}
resources.Match获取匹配的全局资源{{ $images := resources.Match "images/*.png" }}
resources.GetRemote从远程 URL 加载资源{{ $image := resources.GetRemote "https://example.com/image.jpg" }}
resources.FromString从字符串创建资源{{ $js := "var x = 1;" | resources.FromString "js/script.js" }}

资源转换管道

转换管道是资源管理系统的关键功能，允许对资源进行链式转换。

转换流程

来源：resources/transform.go94-370 resources/transform.go634-661

转换过程

转换过程通过 ResourceTransformation 接口实现。

每次转换

  1. 接收输入资源
  2. 检查转换结果是否已缓存
  3. 如果未缓存，则执行转换
  4. 将结果存储在缓存中
  5. 返回新的转换后的资源

常见的转换包括：

转换描述示例
Minify（最小化）减小文件大小`{{ $css := resources.Get "css/styles.css"`
Fingerprint（指纹）将内容哈希添加到文件名`{{ $js := resources.Get "js/script.js"`
Concat（连接）合并多个资源`{{ $js := slice $js1 $js2`
ExecuteAsTemplate（作为模板执行）作为 Go 模板处理`{{ $tmpl := resources.Get "tmpl.html"`

来源：resources/transform.go94-99 tpl/resources/resources.go267-301

资源缓存

Hugo 使用多级缓存系统来处理资源，以提高性能，特别是对于图像处理等计算密集型操作。

缓存架构

来源：resources/resource_spec.go110-115 resources/image_cache.go29-125 resources/resource_cache.go31-58

缓存级别

  1. 内存缓存：在内存中缓存，其生命周期持续整个构建过程。

    • 使用 dynacache.Cache 实现。
    • 为不同资源类型分区。
    • 根据资源类型，在重新构建或更改时清除。

  2. 文件缓存：磁盘缓存，在不同构建之间持久存在。

    • 使用 filecache.Cache 实现。
    • 存储转换后的资源和元数据。
    • 用于计算量大的转换（图像、SCSS 等）。

缓存系统确保资源仅在必要时进行转换，从而显著提高构建性能。

图像处理

Hugo 提供了一个全面的图像处理系统来处理图像。这通过 images.ImageResource 接口实现。

图像处理管道

来源：resources/image.go1-143 resources/images/image.go1-178 resources/image_cache.go1-125

图像处理操作

操作描述示例
Resize（缩放）改变尺寸{{ $img := $original.Resize "300x200" }}
Crop（裁剪）裁剪一部分{{ $img := $original.Crop "300x200 TopLeft" }}
Fill（填充）缩放并裁剪以填充{{ $img := $original.Fill "300x200" }}
Fit（适应）缩放以适应{{ $img := $original.Fit "300x200" }}
过滤器Apply filters（应用滤镜）{{ $img := $original.Filter (images.GaussianBlur 5) }}
进程Generic processing（通用处理）{{ $img := $original.Process "resize 300x" }}

来源：resources/image.go207-293 resources/images/image.go176-354

图像格式转换

可以通过在处理操作中指定目标格式，在图像之间进行转换。

支持的格式包括 JPEG、PNG、GIF、TIFF、BMP 和 WebP。

来源：resources/images/config.go47-70 resources/image.go200-232

资源发布

资源在访问其永久链接时发布到输出目录。

发布流程

当对资源调用 .Permalink 或 .RelPermalink 时

  1. 将检查资源是否需要发布。
  2. 如果尚未发布，资源将被写入输出目录。
  3. 输出目录中的路径由资源的目标路径决定。

资源可以配置为延迟发布，即文件创建被推迟直到访问永久链接。

来源：resources/resource.go493-534 resources/transform.go397-409

资源元数据和函数

资源提供各种元数据和函数来访问其属性。

通用资源属性

属性描述示例
.Name资源名称{{ $resource.Name }}
.Title资源标题{{ $resource.Title }}
.ResourceType资源类型{{ $resource.ResourceType }}
.MediaType媒体类型{{ $resource.MediaType }}
.Params自定义参数{{ $resource.Params.author }}
.Data关联数据{{ $resource.Data.Integrity }}
.Content资源内容{{ $resource.Content }}
.Permalink绝对 URL{{ $resource.Permalink }}
.RelPermalink相对 URL{{ $resource.RelPermalink }}

图像资源属性

属性描述示例
.Width图像宽度{{ $image.Width }}
.Height图像高度{{ $image.Height }}
.ExifEXIF 元数据{{ $image.Exif.Date }}
.Colors主色调{{ $image.Colors }}

来源：resources/resource/resourcetypes.go71-156 resources/image.go78-143

集合操作

Hugo 提供了几种处理资源集合的方法。

资源集合方法

方法描述示例
resources.Match获取匹配的资源{{ $images := resources.Match "images/*.jpg" }}
resources.ByType按资源类型过滤{{ $images := resources.ByType "image" }}
resources.Concat合并资源{{ $js := slice $js1 $js2 | resources.Concat "js/bundle.js" }}

来源: tpl/resources/resources.go176-231 resources/resource_factories/create/create.go155-174

结论

Hugo 的资源管理系统提供了一种强大而灵活的方式来处理各种类型的资产。它结合了高效的加载、强大的转换和智能的缓存，以提供高性能，同时提供广泛的功能。

理解这个系统对于开发或扩展 Hugo 的资源处理能力至关重要，特别是对于实现新的资源转换或优化现有资源。

来源: resources/resource.go1-718 resources/transform.go1-767 tpl/resources/resources.go1-331