级联配置
用 cascade 把页面参数、目标与切片级联到多组页面。
这一页解决什么问题
级联(cascade)一次性地给一批页面写入前置元数据:按路径、页面类型、环境或多维站点筛出目标,再把参数灌进去。它是「每个文件都抄一遍同样的 front matter」的替代方案。
最常见的坑:target 的匹配模式写错时没有任何报错——规则没匹配到任何页面,你以为设置生效了,实际一个页面都没拿到参数。所以每写一条规则,都要用结果去验证(见下文与「常见坑」)。
什么时候需要这些设置
| 设置 | 什么时候需要 | 改错了会看到什么现象 |
|---|---|---|
[[cascade]] + cascade.params |
某个分区下所有页面都需要相同的自定义参数(配色、布局、作者) | 参数名写错 → 模板取到空值,页面照常构建,不报错 |
cascade.target.path |
只把值应用到部分路径 | glob 漏写 /** → 只有分区首页生效、下级页面拿不到值,表现为「部分页面异常」 |
cascade.target.kind / environment / sites |
按页面类型、构建环境或多维站点筛选 | 多个筛选键写在同一个 target 里是同时满足的关系;按「或」的预期写会得到空集合 |
多条 [[cascade]] |
不同目标用不同值 | 上游明确按声明顺序依次匹配;两条规则命中同一页面时,顺序会影响最终值 |
本站提示:cascade 是切片类型的键,拆到 config/ 目录时必须写出分区名(见配置简介)。
概述
级联(cascade)会把页面参数和其他前置元数据向下传递给一组页面。默认配置为:
toml
cascade = []在站点配置中,cascade 是切片类型的键,因此必须写出分区名。例如,把 color 页面参数级联到所有页面:
toml
[[cascade]]
[cascade.params]
color = 'red'也可以在页面的前置元数据中配置级联行为,详见前置元数据。
目标
target 键接受一个页面匹配器,用来把级联值限制到部分页面。如果省略 target,级联值会应用到所有页面。
页面匹配器按逻辑路径、页面类型、环境或站点筛选页面,可以使用以下关键字及其任意组合:
| 键名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
environment |
string |
— | glob 模式,匹配构建环境,例如 {staging,production}。 |
kind |
string |
— | glob 模式,匹配页面类型,例如 {taxonomy,term}。 |
lang |
string |
— | 已弃用,请改用 sites 设置。Hugo 0.153.0 起弃用。 |
path |
string |
— | glob 模式,匹配页面的逻辑路径,例如 {/books,/books/**}。 |
sites |
map |
— | 站点矩阵,可匹配语言、版本、角色等内容维度的任意组合。Hugo 0.153.0 及更高版本可用。 |
例如,把 color 页面参数级联到 articles 分区及其所有下级页面,但仅限英语(en)和德语(de)语言站点:
toml
[cascade.params]
color = 'red'
[cascade.target]
path = '{/articles,/articles/**}'
[cascade.target.sites.matrix]
languages = '{en,de}'
target的别名_target已弃用,并将在未来的版本中移除。
切片
在切片中定义多个级联映射,即可为不同目标应用不同的值。例如:
toml
[[cascade]]
[cascade.params]
color = 'red'
[cascade.target]
path = '{/articles,/articles/**}'
[[cascade]]
[cascade.params]
color = 'blue'
[cascade.target]
path = '{/tutorials,/tutorials/**}'上例会依次匹配各条级联规则,先为 /articles 分区设置 color = 'red',再为 /tutorials 分区设置 color = 'blue',未命中任何目标的页面不受影响。
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
| 级联「设了」,页面完全没变化 | target 的 glob 没匹配到任何页面,而 Hugo 不报错 |
先用省略 target 的写法验证参数能否生效,再逐步收紧匹配范围 |
| 只有分区首页生效,子页面没有 | path 只写了 /articles,没带 /** |
写成 '{/articles,/articles/**}' 这类模式 |
| 参数取到空值 | 参数写在了 [cascade] 下,而不是 [cascade.params] 下 |
页面参数放 cascade.params;其它前置元数据字段直接写在 cascade 下 |
配置拆到 config/ 目录后失效 |
cascade 是切片类型,拆分文件时必须写出分区名 |
文件里写成 [[cascade]],不要只写裸切片 |
| 多条规则互相覆盖 | 规则按声明顺序依次匹配,后写的会影响先写的 | 调整声明顺序,或把 target 收紧到互不重叠 |