从模板创建资源
用 resources.ExecuteAsTemplate 把模板资源按给定上下文执行后发布。含上下文选择、缓存键陷阱与完整示例。
开始之前,你需要
- 会写几个基本的 Go 模板动作(
{{ }}、with、$),知道.在with里会被重新绑定 - 读过简介,知道资源要经
Publish/Permalink/RelPermalink才会被发布
读完之后你能
- 把一份存放在
assets/里的模板(例如 CSS)用站点配置渲染成最终文件并发布 - 解释第二个参数为什么常写成
$而不是.,以及上下文写错时会出现什么现象 - 判断什么时候该用
ExecuteAsTemplate、什么时候resources.FromString就够了
接着读:从字符串创建资源 · 把 Sass 编译为 CSS · ExecuteAsTemplate
这一页解决什么问题
Sass 变量能在编译期注入配置值,但那需要整条 Sass 工具链。如果只是想把少量配置值填进一份文本文件(CSS 里的颜色、JSON 里的站点名、XML 里的域名),用 Go 模板直接渲染更轻。
resources.ExecuteAsTemplate 就是这条路径:把 assets/ 里的一份文件当作 Go 模板执行,用你给的上下文渲染出内容,再作为资源发布。
方法签名与用途
resources.ExecuteAsTemplate 把一个资源当作 Go 模板来解析和执行,并返回执行结果对应的资源,缓存键是目标路径:
resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE三个参数依次是目标路径、执行上下文与资源本身;目标路径同时决定发布后的位置与文件名。当调用结果的 Publish、Permalink 或 RelPermalink 方法时,Hugo 会把资源发布到目标路径。
返回值与边界
| 情形 | 会怎样 |
|---|---|
| 正常 | 返回渲染后的资源,可以继续 minify / fingerprint 或直接发布 |
| 模板里引用了上下文中不存在的字段 | 渲染出 <no value> 之类文本(不会让构建失败),产物因此在浏览器里表现为「值不对」 |
模板语法写错(少一个 end、拼错函数名) |
直接构建失败,报错会指出模板位置 |
CONTEXT 传成了 nil |
渲染时取不到任何数据,结果大多为空或 <no value> |
| 同一个目标路径配不同上下文 | 缓存键相同 → 第二次调用直接复用第一次的结果,不同页面拿到同一份内容 |
资源是 nil |
该步失败;先 with 判断资源存在 |
准备模板资源
假设你想让一份 CSS 使用项目配置中的颜色值。先把模板放进 assets 目录:
body {
background-color: {{ site.Params.style.bg_color }};
color: {{ site.Params.style.text_color }};
}对应的项目配置如下:
[params.style]
bg_color = '#fefefe'
text_color = '#222'在模板中执行
在 baseof.html 之类的模板里写:
{{ with resources.Get "css/template.css" }}
{{ with resources.ExecuteAsTemplate "css/main.css" $ . }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
{{ end }}这个例子做了三件事:
- 把模板文件取回为资源;
- 以当前页面为上下文执行这个资源;
- 把资源发布到
css/main.css。
注意第二个参数传的是 $ 而不是 .:进入 with 之后 . 已经被重新绑定,用 $ 才能把模板顶层的上下文(页面模板中即当前页面)传给模板执行环节。
执行后的结果大致为:
body {
background-color: #fefefe;
color: #222;
}为什么 . 在这里会出错:with 把 . 改成了「当前资源对象」,而资源对象上没有 site、Params 这些页面级数据。传 . 不报错,只是渲染出一堆空值——这正是本节最容易踩的坑。
上下文与数据来源
CONTEXT 决定模板里能取到哪些数据,示例传入的是当前页面,因此模板中可以直接使用 site、page 等模板对象,也可以访问页面参数。若模板只依赖站点级配置,同样可以传入站点对象;只要保证模板中引用的字段在上下文中存在即可。
怎么选上下文
| 模板里需要什么 | 传什么 |
|---|---|
| 当前页面的标题、参数、资源 | $(页面模板顶层的上下文) |
只用到站点级数据(site.Params、site.BaseURL 等) |
传页面上下文即可,site 从任何上下文都能访问 |
| 需要自定义的一组数据 | 传一个 dict,例如 (dict "color" "blue"),模板里用 .color 取 |
完整可运行示例
这个示例把「配置里的颜色」渲染进一份 CSS 并发布出去。
① 建项目并进入目录:
hugo new project template-resource-demo
cd template-resource-demo② 在项目配置 hugo.toml 末尾加上颜色:
[params.style]
bg_color = '#fefefe'
text_color = '#222'③ 新建模板资源 assets/css/template.css:
body {
background-color: {{ site.Params.style.bg_color }};
color: {{ site.Params.style.text_color }};
}④ 新建首页模板 layouts/home.html:
{{ with resources.Get "css/template.css" }}
{{ with resources.ExecuteAsTemplate "css/main.css" $ . }}
<!doctype html>
<html lang="zh-cn">
<head>
<meta charset="utf-8">
<title>ExecuteAsTemplate 演示</title>
<link rel="stylesheet" href="{{ .RelPermalink }}">
</head>
<body>
<h1>颜色来自项目配置</h1>
</body>
</html>
{{ end }}
{{ end }}⑤ 构建并查看:
hugo你应当看到什么
-
页面背景是浅灰白(
#fefefe)、文字是深灰(#222)——说明配置值真的被渲染进了 CSS; -
public/css/main.css存在,内容里的模板动作已经消失:cssbody { background-color: #fefefe; color: #222; } -
页面源代码里
<link href="/css/main.css">不带哈希(本示例没有接fingerprint;接上之后会变成main.<哈希>.css); -
对照实验:把
ExecuteAsTemplate的第二个参数由$改成.,重新构建。构建不会失败,但产物里的颜色变成空值或<no value>——这就是「上下文传错」的典型表现。
缓存与 –gc
Hugo Pipes 以整条管道链为缓存单位,resources.ExecuteAsTemplate 另外以目标路径作为缓存键。因此同一个目标路径在一次构建中只会执行一次:如果同一个目标路径被用于内容依赖页面上下文的模板,不同页面之间会复用同一份结果,需要为不同上下文使用不同的目标路径。
hugo build --gc 可在构建后清理未使用的缓存文件,详见命令。生成的文件位于发布目录中,陈旧文件的清理与其他构建产物一致。
这条缓存规则的现实后果:想给每个页面生成一份带该页标题的 CSS,就必须让目标路径带上区分度,例如:
{{ $path := printf "css/%s.css" .File.TranslationBaseName }}否则第二个页面会直接复用第一个页面的结果。
什么时候用 / 什么时候别用
该用的时候
- 少量配置值要填进文本资源(颜色、域名、站点名、版本号);
- 模板文件希望保留独立文件的形态,便于编辑器高亮与版本管理;
- 需要在资源里使用完整的模板能力(
site、now、自定义dict)。
别用的时候
- 内容来自字符串而不是文件:用 resources.FromString 更直接;
- 只有几个颜色值:CSS 自定义属性(
var(--color))往往更简单,改配置时也更容易排查; - 需要完整的 Sass 能力(嵌套、
@use、mixin):用 css.Sass; - 内容固定不变:放进
static/或assets/原样引用即可; - 同一个目标路径要服务多个不同上下文:除非你按上文给路径加上区分度,否则会互相覆盖。
常见坑
① 命令找不到(命令类)
hugo: command not found:见安装 Hugo;- 本函数不调用外部命令,因此「找不到可执行文件」一类报错来自上游管道(例如
css.Sass需要 Dart Sass)。
② 没报错但结果不对(静默失败类)
| 现象 | 原因 | 怎么确认 |
|---|---|---|
产物里出现 <no value> 或空字符串 |
上下文传错(写成 .),或配置里的键名与模板中不一致 |
把第二个参数改成 $;核对 [params.style] 的层级 |
产物里原样出现 {{ ... }} |
把它当成了普通资源,没有经过 ExecuteAsTemplate |
检查是否漏了这一步 |
public/ 里找不到生成的文件 |
结果没有被 .RelPermalink / .Permalink / .Publish 引用 |
看模板是否输出了 <link> 或调用了发布方法 |
| 所有页面拿到同一份内容 | 多个上下文共用了同一个目标路径 | 给目标路径加上页面维度 |
| 改了模板文件,产物没变 | 管道链缓存未失效 | hugo --ignoreCache 重建 |
| 浏览器按 MIME 类型处理错了 | 目标路径的扩展名不对(例如发布成 .txt) |
让目标路径沿用 .css / .js / .json 等正确扩展名 |
③ 报错看不懂(报错类)
- 报错里出现
unexpected "}" in template/unexpected EOF一类:模板语法错误,报错位置指向模板文件,从那里读起; - 报错里出现
function "xxx" not defined:模板里用了不存在的函数名(拼写错误,或函数在当前 Hugo 版本里没有); - 报错里出现
can't evaluate field RelPermalink:上游返回了nil,补上with; - 构建成功但浏览器里样式不对:多半是上下文或键名问题(见上表),而不是模板执行失败;
- 报错指向的文件与你改的无关:渲染期问题常这样出现,见故障排查。
排查顺序:资源路径对不对 → 上下文($ 还是 .)→ 模板里的键名是否存在 → 目标路径与 MIME 类型 → 缓存是否干扰。