配置

版本配置

定义内容版本、默认版本与版本权重排序。

这一页解决什么问题

版本(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)是内容变化的维度之一,与语言(面向本地化)、角色(面向受众)并列。借助版本,你可以用语义化版本同时维护同一内容的不同迭代、发布或生命周期状态,并在一次构建中生成多个版本的站点。

以下为默认配置:

toml
[versions."v1.0.0"]
weight = 0

也就是说,默认情况下项目只定义了一个版本 v1.0.0,其权重为 0。

基础设置

在站点配置文件中配置以下基础设置:

toml
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)的选取。

示例

下面的配置演示了如何定义多个版本并分别指定权重:

toml
[versions."v1.0.0"]
weight = 20
[versions."v2.0.0"]
weight = 10

v2.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,或暂不使用该维度

更多排查入口见故障排查。