Hugo 0.152.0–0.155.x 升级指南

本文总结 Hugo 0.152.0 至 0.155.3 的破坏性变更与重要变化，是 Docsy 0.14.0 与 0.13.0 发布和升级指南的配套文章。

升级摘要

本指南重点说明 Hugo 0.152.0–0.155.x 的破坏性变更，以及可能需要执行的操作。

• 审阅 BREAKING 变更：
  • YAML yes/no Token 变为字符串
  • 多维站点的构建顺序发生变化
• 审阅 弃用项（不具破坏性，但建议处理）：
  • Mount 的 lang 选项已弃用
  • includeFiles/excludeFiles 已弃用
• 可以快速浏览：
  • 已知问题与修复
  • 重要变化
• 准备好后，直接阅读升级到 Hugo 0.155.x

YAML yes/no Token 变为字符串（0.152.0）

0.152.0（2025-10-21）升级到更现代的 YAML 库，导致配置文件和页面 Front Matter 中某些 Token 的解释方式发生破坏性变化。

过去，未加引号的 yes、no、on、off 等 Token 会被视为布尔值；现在它们会被视为字符串。完整 Token 列表见 0.152.0 发布说明。

操作：必需与可选

• 适用条件：项目 YAML 中存在未加引号的 yes、no、on、off 等 Token。请把它们改为 true 或 false。

  搜索以下未加引号的键或值：

  • yes、Yes、YES、y、Y、on、On、ON：改为 true；
  • no、No、NO、n、N、off、Off、OFF：改为 false。

  示例：

  # OLD (now broken in 0.152.0+)
  enabled: yes
  disabled: no
  
  # NEW (correct)
  enabled: true
  disabled: false
  

• 适用条件：项目有自定义页面反馈配置。现在可以删除包含 yes、no 等 Token 的键（或值）外层引号。

  # OLD
  params:
    ui:
      feedback:
        enable: true
        'yes': Glad to hear it! ...
        'no': Sorry to hear that. ...
  
  # NEW
  params:
    ui:
      feedback:
        enable: true
        yes: Glad to hear it! ...
        no: Sorry to hear that. ...
  

多维内容模型（0.153.0）

0.153.0（2025-12-19）引入了强大的多维内容模型。借助新的 sites.matrix 配置，除原有语言维度外，还能按版本和角色组织站点。

下面总结与多维站点相关的破坏性变更和弃用项。

多维站点的构建顺序

Hugo 现在根据排序后的维度构建站点——先按权重，再按名称——而不再从默认内容语言开始。.Site.Sites 的排序也会受到影响。

操作：必需与可选

适用条件：项目依赖特定的站点构建顺序，或按位置索引 .Site.Sites，例如通过下标访问。请改为显式选择默认站点。

具体修复取决于访问站点的方式。例如，代码包含 index site.Sites 0 时，应替换为 site.Sites.Default。更多实际示例见 open-telemetry/opentelemetry.io#8850。

弃用项

Mount 的 lang 选项已弃用

操作（建议）

适用条件：Mount 使用 lang。请切换到 sites.matrix，以消除弃用警告。

示例：

# OLD (deprecated)
- source: content/fr
  target: content
  lang: fr

# NEW
- source: content/fr
  target: content
  sites:
    matrix:
      languages: ['fr']

实际示例见 open-telemetry/opentelemetry.io#9070。

includeFiles/excludeFiles 已弃用

Mount 的 includeFiles/excludeFiles 选项已经弃用，请改用支持取反的 files Filter。

操作（建议）

适用条件：Mount 使用 includeFiles 或 excludeFiles。请切换到 files，以消除弃用警告。

示例：

# OLD (deprecated)
- source: content
  target: content
  excludeFiles: ['drafts/**']

# NEW
- source: content
  target: content
  files: ['! drafts/**']

实际示例见 open-telemetry/opentelemetry.io#9070。

已知问题与修复

0.153.x 中的别名处理

重要变化

以下重要变化不具破坏性。

0.155.0

• Sites Matrix 支持版本与维度范围查询，例如 >= v1.0.0；
• 页面别名可以在多维站点中正确工作；
• 新增 XMP 与 IPTC 图片元数据支持。

0.154.0–0.154.5

• 引入 Partial Decorator（inner 关键字），提供强大的模板组合能力；
• 新增 Page.OutputFormats.Canonical 方法（0.154.4）；
• 新增 reflect.* 函数，例如 reflect.IsPage；
• 修复多维/多主机环境中的关键别名与站点重定向问题。

0.153.0

• WebP 编解码改为通过 WASM 使用 libwebp，处理 WebP 不再需要 Extended 版本；
• 支持动态 WebP，包括与动态 GIF 相互转换；
• GoogleAnalytics.RespectDoNotTrack 默认值改为 true；
• 删除重复内容路径警告，输出更安静，但也可能隐藏问题；
• macOS 发行包 现在只提供经过签名与公证的 .pkg 安装程序，不再支持 .tar.gz。详见下方说明。

升级到 Hugo 0.155.x

处理所有破坏性变更和弃用项后，升级到 Hugo 0.155.x 的最新版本。使用 hugo-extended NPM 软件包时，可以运行：

npm install hugo-extended@latest

使用 hvm 管理 Hugo 版本时，可以运行：

hvm use latest

建议的最低 Hugo 版本

使用新 Sites Matrix 功能，而且希望获得多维站点中最新别名修复与支持的项目，建议使用 Hugo 0.157.0 或更高版本：

module:
  hugoVersion:
    min: '0.157.0'

• ←上一页
• 下一页→