Hugo Pipes on Hugo 中文文档

简介

Thu, 01 Oct 2026 00:00:00 +0800

在 assets 中查找资源

这里讨论的是全局资源与远程资源：

全局资源: assets 目录中的文件，或位于任何挂载到 assets 目录的目录中的文件。
远程资源: 位于远程服务器上、可通过 HTTP 或 HTTPS 访问的文件。

若资源的作用域属于某个 Page，请参阅页面资源一节。

把 Sass 编译为 CSS

Thu, 01 Oct 2026 00:00:00 +0800

适用前提

用 css.Sass 函数把 Sass 转译为 CSS。Hugo 的 extended 版与 extended/deploy 版内置了 LibSass 转译器；若想使用 Sass 语言的最新特性，则需另行安装 Dart Sass。Sass 有 SCSS 与缩进语法两种书写形式，Hugo 都支持。

PostCSS

Thu, 01 Oct 2026 00:00:00 +0800

适用前提

用 css.PostCSS 函数配合 PostCSS 及其任意插件来转换 CSS。PostCSS 运行在 Node.js 之上，因此本机需要安装 Node.js；此外，处理过程会在项目根目录执行 postcss 命令，该命令必须已经在项目里安装好。

JavaScript 构建

Thu, 01 Oct 2026 00:00:00 +0800

用 js.Build 可以：

打包（bundle）
转译（TypeScript 与 JSX）
摇树（tree shake，移除无用代码）
压缩（minify）
生成 source map

{{ with resources.Get "js/main.js" }}
  {{ $opts := dict
    "minify" (cond hugo.IsDevelopment false true)
    "sourceMap" (cond hugo.IsDevelopment "linked" "none")
  }}
  {{ with . | js.Build $opts }}
    {{ if hugo.IsDevelopment }}
      <script src="{{ .RelPermalink }}"></script>
    {{ else }}
      {{ with . | fingerprint }}
        <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

安装 Node.js 依赖

凡是不在 assets 目录内的导入，或者无法解析到 assets 内某个组件的导入，都会交给 esbuild 处理，并以项目目录作为解析起点，也就是说，查找 node_modules 之类的目录时都从项目根目录开始。因此，如果项目引用了 npm 依赖，必须先运行 npm install 再执行构建；若正在开发一个需要被导入、且依赖自身 package.json 中那些依赖的主题或组件，可用 hugo mod npm pack 把项目中的 npm 依赖汇总起来。

资源打包

Thu, 01 Oct 2026 00:00:00 +0800

方法签名与用途

resources.Concat 把一个资源切片拼接为一份资源，并以目标路径作为缓存键。签名如下：

resources.Concat TARGETPATH [RESOURCE...]

返回值类型是 resource.Resource，因此拼接结果可以继续接入 Hugo Pipes 的其他环节。切片中的每个资源必须具有相同的媒体类型；媒体类型不同的资源不能拼接在一起。

资源压缩

Thu, 01 Oct 2026 00:00:00 +0800

方法签名与用途

resources.Minify 返回给定资源的最小化版本，参数就是资源对象：

resources.Minify RESOURCE

它还有一个别名 minify，这也是管道写法中最常用的形式。两者完全等价：

{{ $css := resources.Get "css/main.css" }}
{{ $style := $css | minify }}

返回值类型同样是 resource.Resource。可以压缩的资源类型为 CSS、JS、JSON、HTML、SVG 与 XML，其他类型不在支持范围内。

资源指纹

Thu, 01 Oct 2026 00:00:00 +0800

方法签名与用途

resources.Fingerprint 对资源内容做密码学哈希，返回带哈希值的资源对象，用于缓存失效与子资源完整性校验：

resources.Fingerprint [ALGORITHM] RESOURCE

它也有别名 fingerprint。哈希算法可以是 md5、sha256（默认）、sha384 或 sha512。虽然最常见的用途是 CSS 与 JavaScript，但任何类型的资源都可以做指纹。

从字符串创建资源

Thu, 01 Oct 2026 00:00:00 +0800

方法签名与用途

resources.FromString 从一个字符串创建资源，并以目标路径作为缓存键：

resources.FromString TARGETPATH STRING

返回值类型是 resource.Resource，因此它可以继续参与管道，例如压缩或指纹。它适合生成那些内容来自配置或模板变量、而非来自磁盘文件的资源，典型的例子是 security.txt 与 robots.txt。

从模板创建资源

Thu, 01 Oct 2026 00:00:00 +0800

方法签名与用途

resources.ExecuteAsTemplate 把一个资源当作 Go 模板来解析和执行，并返回执行结果对应的资源，缓存键是目标路径：

resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE

三个参数依次是目标路径、执行上下文与资源本身；目标路径同时决定发布后的位置与文件名。当调用结果的 Publish、Permalink 或 RelPermalink 方法时，Hugo 会把资源发布到目标路径。