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

gohugoio/hugo

菜单

资源管道

相关源文件

Hugo 的资源管道是一个强大的系统，用于处理和转换资源，如图像、CSS、JavaScript 和其他资产。本页描述了资源如何通过 Hugo 的转换管道进行流动，包括资源获取、处理、缓存和发布。

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

概述

资源管道使站点开发者能够：

  • 对资源应用转换（调整大小、裁剪、压缩、指纹等）
  • 将多个转换链接在一起
  • 缓存已转换的资源以提高性能
  • 将资源发布到输出目录

来源：resources/transform.go resources/resource.go resources/resource_cache.go

资源类型

Hugo 的资源系统建立在一组接口和实现之上，这些接口和实现代表了不同类型的资源。

内部实现

在内部，Hugo 使用几个结构体来实现这些接口：

  • genericResource：基础资源实现，处理大多数常见的资源操作。
  • imageResource：扩展了通用资源，增加了特定于图像的功能。
  • resourceAdapter：包装资源以处理转换链。

来源：resources/resource/resourcetypes.go resources/resource.go resources/image.go

资源获取

资源可以通过三种主要方式获取：

页面资源

页面资源是页面包的一部分文件。它们可以通过页面上的 .Resources 变量访问。

全局资源

全局资源是存储在 assets/ 目录中的文件。它们可以使用 resources.Get 函数访问。

远程资源

远程资源是从外部 URL 获取的。它们可以使用 resources.GetRemote 函数访问。

字符串资源

还可以使用 resources.FromString 函数从字符串创建资源。

来源：resources/resource_factories/create/create.go tpl/resources/resources.go

转换管道

转换管道是资源处理系统的核心。它允许对资源应用一系列转换。

转换上下文

管道中的每个转换都会收到一个上下文对象（ResourceTransformationCtx），其中包含：

  • 输入和输出读写器
  • 源路径和目标路径
  • 媒体类型
  • 自定义数据
  • 发布助手

可用转换

Hugo 提供了许多内置转换：

图像转换

  • Resize：将图像调整到指定尺寸。
  • Crop：将图像裁剪到指定尺寸。
  • Fill：缩放并裁剪图像以填充指定尺寸。
  • Fit：缩放图像以适应指定尺寸。
  • Filter：对图像应用滤镜。
  • Process：通用图像处理（组合以上操作）。

通用转换

  • Minify：压缩 CSS、JS、HTML、XML、JSON 或 SVG 内容。
  • Fingerprint：向文件名添加内容哈希。
  • PostProcess：在构建后处理资源。
  • ExecuteAsTemplate：将内容作为 Go 模板处理。
  • Concat：将多个资源连接成一个。
  • Copy：创建一个资源副本，并指定新的目标路径。

转换链示例

此链：

  1. 获取 SCSS 资源。
  2. 将其转换为 CSS。
  3. 压缩 CSS。
  4. 向文件名添加基于内容的文件指纹。
  5. 返回带有完整性数据的已转换资源。

来源：resources/transform.go hugolib/resource_chain_test.go resources/image.go

资源缓存

Hugo 采用复杂的缓存系统来避免重新处理未更改的资源。这对于计算量大的操作（如图像处理）尤其重要。

内存缓存

内存缓存会在构建期间将资源及其转换后的版本存储在内存中。它被组织成不同类型资源的“分区”：

  • /res1：通用资源。
  • /res2：基于文件的资源。
  • /resr：远程资源。
  • /ress：资源集合。
  • /restransform：转换后的资源。
  • /imgs：图像资源。

文件缓存

文件缓存将转换后的资源持久化到磁盘，以跨构建使用。这对于以下情况尤其重要：

  • 图像转换。
  • SCSS/SASS 编译。
  • PostCSS 处理。
  • 其他耗时的转换。

Hugo 将这些缓存的资源存储在 .hugo_build.lock 目录中。

缓存键

Hugo 使用基于内容的哈希来生成转换资源的缓存键。

  1. 对于内存缓存：资源路径和转换参数的哈希。
  2. 对于文件缓存：资源内容和转换参数的哈希。

这确保了只有在资源内容或转换参数发生变化时才会重新处理资源。

来源：resources/resource_cache.go resources/image_cache.go

资源发布

当资源的 Permalink 或 RelPermalink 方法被调用，或者 Publish 方法被显式调用时，资源会被发布到公共目录。

惰性发布

默认情况下，Hugo 使用惰性发布，这意味着资源仅在需要时才发布。这种情况发生于：

  1. 在模板中访问资源的 Permalink 或 RelPermalink。
  2. 显式调用 Publish 方法。

即时发布

某些资源会立即发布，无论其永久链接是否被访问。这包括：

  1. 从内容文件创建的资源。
  2. 作为页面包一部分的资源。

发布流程

当资源被发布时：

  1. 如果目标目录不存在，则会创建它们。
  2. 资源内容会被复制到目标文件。
  3. 任何额外的文件（如源映射）也会被发布。

Hugo 确保每个资源只发布一次，即使其永久链接被多次访问。

来源：resources/resource.go397-537

与其他 Hugo 系统的集成

资源管道与其他 Hugo 系统集成：

  • 媒体类型：资源具有相关的媒体类型，这些类型决定了它们如何被处理和提供。
  • 输出格式：资源可以以不同的格式（HTML、JSON 等）发布。
  • 多语言：资源可以是特定于语言的，也可以跨语言共享。
  • 模块系统：资源可以来自 Hugo 模块。

扩展资源管道

资源管道可以通过 Hugo 的模块系统进行扩展，允许：

  • 自定义资源转换。
  • 自定义资源类型。
  • 自定义发布策略。

这是一个高级主题，需要 Go 编程知识，超出了本页的范围。

来源：resources/transform.go resources/resource.go