Hugo 0.158.0–0.164.x 升级指南

本文是 Docsy 0.16.0 发布文章的配套指南；后者说明了 0.16.0 要求并验证过的 Hugo 版本。

升级摘要

• 以下情况适合阅读本指南：
  • 升级到 Docsy 0.16.0；
  • 只升级 Hugo。
• 审阅 BREAKING 变更：
  • 由 Hugo 管理的 Node 工具要求 Node 22+；
  • HTML 内容与符号链接的安全规则发生变化。
• 审阅 弃用项：
  • 语言配置与模板 API；
  • 图片处理配置与模板 API。
• 可以快速浏览：
  • Markdown 链接转义；
  • 图片 URL 变动；
  • 模板与 Module 清理；
  • 更快的构建与更严格的模板；
  • 重要变化。
• 准备好后，直接阅读升级到 Hugo 0.164.0。

语言 API 弃用项（0.158.0）

Hugo 0.158.0 重命名了若干语言配置项和模板方法。按照 Hugo 的弃用时间线，旧名称会先记录弃用通知，随后升级为警告，最终变为错误。

Docsy 自身的模板和文档已经改用新名称——这也是 0.16.0 提高 Hugo 最低版本的原因之一。

操作

适用条件：多语言站点配置使用旧语言字段。请适时重命名，并检查语言菜单输出：

# OLD
languages:
  en:
    languageName: English
    languageDirection: ltr

# NEW
languages:
  en:
    label: English
    direction: ltr

适用条件：站点覆盖语言相关模板或 Partial。请在自定义模板代码中检查以下替换：

当前 Docsy 示例见多语言支持。

Markdown 链接转义（0.159.2，0.160.0 修复）

Hugo 0.159.2 包含一项针对 Markdown 链接和图片危险 URL 的安全修复，但也引入了回归：渲染后的 Markdown 链接 URL 中，& 可能被重复转义，在 HTML 输出中变为 &。

Hugo 0.160.0 修复了该回归，而 0.160.1 是更安全的 0.160.x 补丁版本。Docsy 0.16.0 的 Hugo 最低版本为 0.160.1，已经避开这一问题窗口。

操作

适用条件：曾短暂测试或部署 Hugo 0.159.2。请在生成的 HTML 链接 URL 中搜索 &。

模板与 Module 清理（0.159.x–0.160.x）

Hugo 0.159.x 延续了若干清理工作，旧 Docsy 站点、Docsy 分支或拥有本地模板覆盖的大型下游站点可能遇到这些问题。

操作

适用条件：站点有自定义模板、Module Mount 或转换脚本。

• 用 hugo.Data 替代已弃用的 site.Data；
• 用 files 替代已弃用的 Module Mount 选项 includeFiles 与 excludeFiles；
• 用 :contentbasename 替代已弃用的永久链接占位符 :filename；
• 如果运行 hugo mod npm pack，升级后进行测试；
• 如果使用 hugo convert，提交前审阅生成输出。

适用条件：站点使用 Goldmark Passthrough、RenderShortcodes 或多语言根分区。Hugo 0.160.1 修复了此版本范围内与标题中的 Passthrough 元素、短代码渲染上下文标记和多语言根分区生成有关的回归；烟雾测试应覆盖这些页面。

Node 管理的工具（0.161.x）

Hugo 0.161.x 在 Node 的 --permission 沙箱中运行 PostCSS、Babel、Tailwind 等 Node 工具，因此要求 Node 22 或更高版本。

Docsy 站点通常使用 PostCSS 处理 CSS，所以即使 Docsy 主题本身没有变化，这也可能是实际破坏性变更。Hugo 0.163.2 与 0.163.3 修复了权限模型回归，PostCSS 流水线应优先使用 0.163.3 或更高版本。

操作

适用条件：站点使用 Hugo 0.161.x 或更高版本，并在 Hugo 构建期间运行 PostCSS、Babel、Tailwind 或类似 Node 工具。

• 把 Node 升级到当前活跃 LTS；Docsy 0.16.0 使用 Node LTS 24；
• 在本地构建并检查 Node 权限错误；
• 如果 CI 把 node_modules 放在项目树之外——例如 Netlify 共享缓存——且构建以 ERR_ACCESS_DENIED 失败，请升级到 Hugo 0.163.2 或更高版本；
• 如果 PostCSS 或 Babel 配置使用 .mjs/.cjs 变体，例如 postcss.config.mjs，请使用能够解析这些变体的 Hugo 0.163.3；
• 使用 Tailwind 的项目应将 Tailwind 安装为 NPM 软件包；Hugo 不再支持这条路径中的独立 Tailwind 二进制文件；
• Node 工具确实需要创建子进程，却被 Hugo 0.161.1 或更高版本拦截时，请审阅 security.node.permissions.AllowChildProcess。

内容与资源安全（0.161.x–0.163.x）

Hugo 在这一版本范围内收紧了多项安全边界：

• security.http.urls 默认值更严格，resources.GetRemote 会重新检查重定向；
• 除非通过 security.allowContent 允许，否则默认拒绝 text/html 内容文件；
• 更多模板/资源函数会拒绝或忽略符号链接条目，包括 resources.Get，以及 0.163.1 中的 os.ReadDir、os.ReadFile、os.Stat 与 os.FileExists。

操作

适用条件：站点使用远程资源、手写 .html 内容文件、符号链接内容/资源，或在缓存 Partial 中使用 templates.Defer。

• 使用目标 Hugo 版本在本地构建，审阅安全相关错误与警告；
• 有意发布 .html 内容文件时，显式配置 security.allowContent；
• 模板调用 resources.GetRemote 时，审阅 security.http.urls 并测试会发生重定向的 URL；
• 内容或资源通过符号链接进入项目时，测试相关页面；如果 Hugo 拦截，应考虑改用 Hugo Mount 或真实文件；
• 模板在 partialCached 内使用 templates.Defer 时，把延迟工作移到缓存 Partial 外部；Hugo 现在会报告这种无效组合，而不是静默产生错误结果。

图片处理弃用项与 URL 变动（0.163.x）

Hugo 0.163.0 弃用全局图片质量配置，改为按格式设置；同时新增 AVIF 相关配置，并修改内部缩放图片缓存键。

操作

适用条件：站点配置使用全局 imaging.quality 或 imaging.compression。

• 改为按格式设置；如果取值与 Hugo 默认值相同，也可以直接删除；

• 站点依赖 Docsy 风格的锐利照片缩小时，保留 resampleFilter: CatmullRom：

  imaging:
    resampleFilter: CatmullRom
  

图片 URL 变动

适用条件：站点提交生成输出、比较 Public 构建，或使用会积极缓存生成图片资源的 CDN。

在 Hugo 0.161.x–0.163.x 中，即使源图片与视觉输出不变，包含 _hu_<HASH> 的缩放图片文件名也可能变化。这是预期的缓存键变动，可能产生嘈杂 Diff 与缓存未命中，但通常并非内容回归。出现差异时，应检查实际渲染图片，而不只是文件名。

更快的构建与更严格的模板（0.164.0）

Hugo 0.164.0 修复了一项影响 0.128.0 至 0.163.x 的模板渲染性能下降。大型站点收益最明显：在一个约 8,500 页的 Docsy 站点报告中，完整构建时间从 608 秒降到 117 秒（见性能讨论）。

同一版本还收紧模板处理，并更新语法高亮：

• resources.PostProcess 已弃用，请改用 templates.Defer；Docsy 模板没有使用 resources.PostProcess；
• 指定的 View 模板缺失时，.Render 现在会令构建失败，而不是静默不输出；嵌套 View 名称恢复正常；
• 内置 Chroma 会重新 Tokenize protobuf、YAML、Markdown 等语言：语法高亮 class 会变化，文本内容不变；
• 多语言 Sitemap 中，每个 URL 的 xhtml:link 备用项现在优先列出该条目自身语言。

操作

适用条件：站点规模较大，覆盖或新增模板，或者提交生成输出。

• 对干净的生产构建进行基准测试；模板密集型站点的构建时间可能大幅改善；
• 在自定义模板中用 templates.Defer 替代 resources.PostProcess；
• 修复所有引用缺失 View 模板的 .Render 调用；它们现在会令构建失败；
• 把语法高亮 class 变化与 Sitemap 备用链接排序变化视为预期输出变动。

其他弃用项与重要变化

模板与配置弃用项

站点有自定义模板、外部内容转换器或 JavaScript 工具配置时，请审阅以下事项：

• .IsNode 已弃用，请改用 .IsBranch；
• 已删除 jsconfig 的 baseUrl 支持；
• 如果从 Module Mount 页面读取 Git 元数据，请验证 .Page.GitInfo 输出。Hugo 0.162.0 修复了 go.mod 位于仓库子目录的 Module 的 GitInfo 处理；
• 使用 --renderSegments 时，优先选择修复 Segment 合并的 Hugo 0.163.1；
• 站点设置 uglyURLs: true，而且页面与分区同名——例如 download.htm 与 download/ 并存——时，请使用 Hugo 0.163.3，它修复了 0.163.x 早期引入的渲染冲突；
• 通过外部转换器渲染 Pandoc 或 reStructuredText 内容时，Hugo 0.163.2 会在缺少转换器二进制文件时 令构建失败（与 AsciiDoc 一致），不再静默发布原始内容；所有构建环境都必须安装转换器。

安全修复

该版本范围包含多项安全更新，包括 Go html/template 修复，以及更严格的 URL/内容处理。Hugo 0.163.3 还加强了默认代码块渲染钩子：围栏代码块的语言 Token（Info String）现在会转义，这对渲染不可信 Markdown 的站点尤其重要。因此，与停留在 0.160.1 相比，更应优先使用 0.163.3 或更高版本。

值得了解的新功能

• css.Build 以及后续 hugo:vars 支持可能有助于站点专属 CSS 流水线，但 Docsy 尚未把 Sass/PostCSS 流水线迁移到 css.Build；
• 0.162.x–0.163.x 新增并持续调整 AVIF 图片处理；
• Hugo 0.158.0 或更高版本为模板作者提供 strings.ReplacePairs；
• Hugo 0.164.0 的 hugo gen chromastyles 新增 --mode 与 --modeSelector 参数，可以生成合并的浅色/深色语法高亮样式表。

升级到 Hugo 0.164.0

处理所有适用的破坏性变更与弃用项后，升级到 Hugo 0.164.0。

使用 hugo-extended NPM 软件包：

npm install --save-exact --save-dev [email protected]

使用 hvm：

hvm use 0.164.0/extended

其他安装方式见安装 Hugo。

基本检查

确认已经处理适用于站点的每项操作，然后：

• 如果升级属于 Docsy 0.16.0 的一部分，请继续其升级章节；
• 否则，以通用站点检查收尾。

• ←上一页
• 下一页→