版本配置
定义内容版本、默认版本与版本权重排序。
这一页解决什么问题
版本(version)是内容变化的维度之一,与语言(面向本地化)、角色(面向受众)并列:同一份内容可以按不同迭代或生命周期状态各出一个版本,并在一次构建中生成多个版本的站点。这一页定义有哪些版本、默认版本是谁、版本之间怎么排序。
普通单版本站点不需要配置这里——默认已经定义了一个 v1.0.0(权重 0)。只有当你确实要同时维护多套内容版本时才需要往下读。
什么时候需要这些设置
| 设置 | 什么时候需要 | 改错了会看到什么现象 |
|---|---|---|
[versions."vX.Y.Z"] |
同一内容要同时维护多个迭代(例如 v1 与 v2 文档) | 版本名不写成语义化版本号 → 后续排序失去依据,只能靠权重兜底 |
versions.<名>.weight |
想让某个版本排在前面(权重升序,小的在前) | 权重都为 0 → 退化为按语义化版本降序排列,顺序可能与预期相反 |
defaultContentVersion |
指定默认版本 | 上游明确要求该值必须与某个已定义版本名一致;不一致时行为不在文档保证范围内,别赌——逐字核对版本名。项目未定义任何版本时会回退为 v1.0.0 |
defaultContentVersionInSubdir |
希望各版本发布路径结构统一(默认版本也进入同名子目录) | 保持 false 而其它版本都在子目录里 → 默认版本的 URL 与其它版本不一致,站内链接容易写错 |
注意
versions配置自 Hugo v0.153.0 起提供。
版本(version)是内容变化的维度之一,与语言(面向本地化)、角色(面向受众)并列。借助版本,你可以用语义化版本同时维护同一内容的不同迭代、发布或生命周期状态,并在一次构建中生成多个版本的站点。
以下为默认配置:
[versions."v1.0.0"]
weight = 0也就是说,默认情况下项目只定义了一个版本 v1.0.0,其权重为 0。
基础设置
在站点配置文件中配置以下基础设置:
defaultContentVersion = 'v1.0.0'
defaultContentVersionInSubdir = false| 键名 | 类型 | 默认值 | 含义 |
|---|---|---|---|
defaultContentVersion |
string |
'' |
项目的默认版本。定义了一个或多个版本时,该值必须与某个已定义的版本名一致。 |
defaultContentVersionInSubdir |
bool |
false |
是否把默认内容版本发布到与 defaultContentVersion 同名的子目录。 |
把 defaultContentVersionInSubdir 设为 true 后,默认内容版本会发布到与 defaultContentVersion 同名的子目录中,使各版本的发布路径保持统一的结构。
版本设置
用下面的设置定义 Hugo 如何为各版本排序。
| 键名 | 类型 | 默认值 | 含义 |
|---|---|---|---|
versions |
map |
{'v1.0.0': {weight = 0}} |
版本映射,键为版本名,值为该版本的设置。 |
versions.<版本名>.weight |
int |
0 |
该版本的权重。设为非零值时,它是该版本的首要排序依据。 |
weight 设为非零值才会成为首要排序依据;保持 0 或未定义时,该版本只能依靠后续的语义化版本次序来决定位置。
排序顺序
Hugo 先按权重升序排序版本,再按各版本的语义化版本降序排序。这会影响构建顺序,以及互补站点(sites complements)的选取。
示例
下面的配置演示了如何定义多个版本并分别指定权重:
[versions."v1.0.0"]
weight = 20
[versions."v2.0.0"]
weight = 10v2.0.0 的权重是 10,小于 v1.0.0 的 20,因此 v2.0.0 排在前面。如果两个版本的权重相同或都未设置,则改由语义化版本次序决定,版本号较大的排在前面。
注意事项
- 版本名建议直接使用语义化版本号(形如
v1.0.0),这样才能获得预期的排序结果。 - 定义多个版本时,
defaultContentVersion的取值必须能在已定义的版本名中找到;当项目没有定义任何版本时,默认版本回退为v1.0.0。 - 版本可以与语言、角色叠加组合,用来精确控制哪些页面在哪些站点上生成。相关说明见内容管理。
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
| 定义了多个版本,构建出来只有默认版本 | 版本维度还需要在内容侧(sites.matrix)声明,只写配置不够 |
参考本页「注意事项」,并见内容管理中的多维站点说明 |
| 版本顺序与预期相反 | 权重都为 0 时,排序依据是语义化版本降序(版本号大的在前) |
需要固定顺序就给非零 weight(升序,小的在前) |
| 默认版本的 URL 与其它版本结构不一致 | defaultContentVersionInSubdir 保持 false |
需要统一路径结构时设为 true |
配置了 defaultContentVersion,但取值在 [versions.*] 里找不到 |
上游要求两者必须一致;未定义任何版本时会回退到 v1.0.0 |
逐字核对版本名(含 v 前缀) |
| 配置似乎被忽略 | 使用的 Hugo 版本低于 v0.153.0 | 升级 Hugo,或暂不使用该维度 |
更多排查入口见故障排查。