templates.Defer
把模板的执行推迟到所有站点与输出格式都渲染完成之后。
这一页解决什么问题
有些模板必须等所有页面都渲染完才能执行。典型场景是 CSS 处理:Tailwind / PurgeCSS 需要先读完 hugo_stats.json(Hugo 渲染完所有页面后才写出的「用到了哪些类名」清单),如果边渲染页面边处理 CSS,就会漏掉后面的类名。templates.Defer 把这段模板推迟到渲染结束阶段再跑。
用法上它有点特别:必须写成 {{ with (templates.Defer (dict ...)) }}…{{ end }},推迟的代码放在 with 块里。
什么时候用,什么时候别用
该用:
- 处理依赖「全站 HTML 统计」的 CSS:
css.TailwindCSS、css.PostCSS+ PurgeCSS; - 需要等所有站点 / 输出格式渲染完才做的收尾计算;
- 想在延迟模板里安全读
site/.RelPermalink(站点、语言、输出格式保持不变)。
别用:
- 普通局部模板 → 直接用
partial; - 在
partialCached里使用 → 实测直接报错(见下); - 在短代码 / 渲染钩子里使用 → 上游提示结果可能不可预期;
- 不需要「全站视角」的模板 → 延迟执行只会让输出顺序更难理解。
用法
templates.Defer 函数把模板的执行推迟到所有站点与输出格式都渲染完成之后。
templates.Defer 函数只接受一个参数,即一个映射,其中可含以下键:
key- (
string)用于该延迟模板的键。它与模板内容的哈希值一起作为缓存键。不指定该键时,Hugo 每次渲染都会执行这个延迟模板,对 CSS、JavaScript 这类共享资源来说效率很低。 data- (
map)可选,作为数据传给延迟模板的映射。在延迟模板中可以通过.或$访问它。
Language Outside: {{ site.Language.Name }}
Page Outside: {{ .RelPermalink }}
I18n Outside: {{ i18n "hello" }}
{{ $data := (dict "page" . )}}
{{ with (templates.Defer (dict "data" $data )) }}
Language Inside: {{ site.Language.Name }}
Page Inside: {{ .page.RelPermalink }}
I18n Inside: {{ i18n "hello" }}
{{ end }}即使执行被推迟,输出格式、站点与语言仍保持不变。在上例中,这意味着延迟模板内部的 site.Language.Name 与 .RelPermalink 与其外部完全一致。
示例
下面的示例把 CSS 处理推迟到 Hugo 渲染完所有页面之后。
处理 Tailwind CSS
css.TailwindCSS 函数会用 hugo_stats.json 判断哪些类名及其它 HTML 标识符被使用。由于 Hugo 必须先渲染完所有页面才能写出该文件,处理 CSS 时要按下面的模板延迟执行:
<head>
{{ with (templates.Defer (dict "key" "global")) }}
{{ partial "css.html" . }}
{{ end }}
</head>{{ with resources.Get "css/main.css" }}
{{ $opts := dict "minify" (not hugo.IsDevelopment) }}
{{ with . | css.TailwindCSS $opts }}
{{ if hugo.IsDevelopment }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ else }}
{{ with . | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
{{ end }}
{{ end }}
{{ end }}要让上面的写法在运行服务器(或 hugo -w)时也工作良好,请添加以下配置:
[build]
[build.buildStats]
enable = true
[[build.cachebusters]]
source = 'assets/notwatching/hugo_stats\.json'
target = 'css'
[[build.cachebusters]]
source = '(postcss|tailwind)\.config\.js'
target = 'css'
[module]
[[module.mounts]]
source = 'assets'
target = 'assets'
[[module.mounts]]
disableWatch = true
source = 'hugo_stats.json'
target = 'assets/notwatching/hugo_stats.json'移除未使用的 CSS
在第 4 步中创建的 postcss.config.mjs 配置文件,会让 PurgeCSS 插件在 css.PostCSS 函数运行时读取 hugo_stats.json。由于 Hugo 只有在所有页面渲染完成后才会写出该文件,CSS 处理必须延迟执行。
- 第 1 步
- 安装 Node.js。
- 第 2 步
- 在项目根目录安装所需的 Node 包:
sh
npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss - 第 3 步
- 构建站点时启用生成
hugo_stats.json文件。如果只在生产构建中使用它,可以考虑把它放到config/production下。toml[build.buildStats] enable = true细节与可选设置参见配置构建。
- 第 4 步
- 在项目根目录为
PurgeCSS与autoprefixer插件创建配置文件。postcss.config.mjsjsimport autoprefixer from 'autoprefixer'; import purgeCSSPlugin from '@fullhuman/postcss-purgecss'; const purgecss = purgeCSSPlugin({ content: ['./hugo_stats.json'], defaultExtractor: content => { const els = JSON.parse(content).htmlElements; return [ ...(els.tags || []), ...(els.classes || []), ...(els.ids || []), ]; }, // https://purgecss.com/safelisting.html safelist: [] }); export default { plugins: [ process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null, autoprefixer, ] }; - 第 5 步
- 把 CSS 文件放到
assets/css目录中。 - 第 6 步
- 延迟 CSS 处理,让它在站点渲染完成后再执行:
layouts/baseof.htmlgo-html-template
<head> {{ with (templates.Defer (dict "key" "global")) }} {{ partial "css.html" . }} {{ end }} </head>layouts/_partials/css.htmlgo-html-template{{ with resources.Get "css/main.css" }} {{ if hugo.IsDevelopment }} <link rel="stylesheet" href="{{ .RelPermalink }}"> {{ else }} {{ with . | postCSS | minify | fingerprint }} <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> {{ end }} {{ end }} {{ end }}
完整示例(实测)
{{ $data := dict "page" . }}
{{ with (templates.Defer (dict "key" "global" "data" $data)) }}
deferred page: {{ .page.Title }}
{{ end }}Hugo 0.167.0 实测渲染:
deferred page: Teach Test你应当看到什么:data 选项把数据传进延迟模板,块内用 .(或 $)访问;key 相同的延迟模板会按「模板内容哈希 + key」缓存。省略 key 也能正常渲染(实测),只是每次渲染都会重新执行,对共享 CSS 这类资源效率更低。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
with (templates.Defer (dict "key" "k" "data" …)) |
块内模板在渲染结束阶段执行,输出回到调用位置 | 否 |
省略 key |
正常工作,但每次渲染都会执行(上游说明效率更低) | 否 |
不带 with 直接调用 |
—— | 是:error calling Defer: Defer does not take any arguments |
在 partialCached 调用的局部模板里使用 |
—— | 是:templates.Defer cannot be used inside a partialCached partial; use partial instead, or move templates.Defer to the calling template |
| 在短代码 / 渲染钩子里使用 | 上游提示结果可能不可预期 | —— |
| 返回类型 | string(签名如此;实际用法是作为 with 的表达式) |
否 |