发布日期: 2026-09-09
版本号: v0.166.0

本次 Hugo 发布以稳定性和缺陷修复为主，同时带来若干值得注意的变更：.Render 现在可以像 partial 一样接收可选的上下文参数，例如把字典传给内容视图；模板中的 return 关键字已重新实现，不再局限于局部模板，可在任意模板以及 if、range 等代码块中使用；新增 resources.Publish 模板函数和 Pages 的 IndexOf 方法；related 相关配置新增用于索引值的 tokenize 选项，索引创建速度也更快；此外还包含多项安全修复。需要注意的兼容性变化包括：用于模块挂载、cascade、segments、部署匹配等场景的 glob 库升级到 1.0.0，匹配引擎被完全重写，修复了大量正确性问题，但格式错误的模式现在会直接报语法错误而不再被静默接受，双星号匹配任意字符但不等于 shell 的 globstar，反斜杠成为转义字符需写成双反斜杠；安全方面，text/org 内容默认被禁止，因为 Org 模式的导出块和 html 片段会原样输出 HTML，存在与 text/html 相同的跨站脚本风险，使用 Org 内容的站点可通过 security.allowContent 重新启用；远程抓取会在建立连接时校验解析后的地址并拒绝回环、私有、链路本地、CGNAT 等地址范围，该检查仅在默认的 security.http.urls 允许列表下生效，若自定义过则视为自行承担，来自 HTTP_PROXY 与 HTTPS_PROXY 的代理会隐藏目标地址因而现在被忽略，除非显式设置 security.http.proxyFromEnvironment 为真；Node.js 工具如 PostCSS、Tailwind CSS 在调用前若发现项目内符号链接指向允许读写根目录之外会直接失败，合法链接需把目标加入 security.node.permissions.allowRead；本身是符号链接的挂载根目录会被丢弃，以补齐 themes 目录的限制，绝对来源路径仍然允许。其他变化还有：在局部模板之外使用 return 现在会报错，此前是被静默忽略；标题中含有斜杠且未显式设置 slug 的页面现在只生成单个 URL 段而不产生嵌套路径，分类和术语页面不受影响；Hugo 改用 Go 1.27 构建。使用 transform.ToMath 且输出选项为 html 或 htmlAndMathml 的站点升级到本版本时必须把模板中引用的 KaTeX 样式表更新到 0.18.4 或更高版本，继续使用 0.16.21 等旧版会导致部分数学与化学表达式渲染错误。缺陷修复涵盖字符串 replaceRE 在零宽断言下的问题、浮点转整型溢出判断的差一错误、透明色与调色板图像的过滤器、同一路径删除多个节点时的切片越界崩溃、阅读时间与模糊字数统计的计算等；改进项包括新增 es2025 构建目标、为 highlight 的 lineAnchors 做转义、优化 common partialCached 的性能、新增内部外部链接忽略 Tailwind CSS 安全错误的配置项、加固默认 http.urls 与地址校验、几何滤镜链保留源调色板并补充基准测试用例、提升 hugo mod init 的健壮性、按转义模式区分延迟模板、转义默认渲染器中代码围栏的属性值、让生成的 npm 工作区包私有且名称稳定、读取映射值排序时保持读锁、改进模板指标时长格式、支持 pandoc 3.11 及更高版本，以及大量依赖库版本升级。

更新内容 （中文）

本次发布主要是加固与 bug 修复，但也有一些值得注意的变更：

  • .Render 现在接受一个可选的上下文参数：{{ .Render "view" $ctx }}，与 partial API 保持一致。这样就可以向内容视图传入例如一个 dict。参见 #15077。
  • 模板中的 return 关键字已重新实现。它现在可以在任何模板中工作（不仅限于 partial），并且可以用在任何地方，例如 if 或 range 块内部。参见 #15212。
  • 新增 resources.Publish 模板函数，以及 Pages 上的 IndexOf 方法。
  • related 配置：索引值新增 tokenize 选项，且索引创建速度更快。
  • 若干安全修复；详见下文说明。

注意事项

  • tpl/transform：在 transform.ToMath 中提升 fileCacheEntryVersion（注意）8d88b8b4 @bep #15267
  • resources/images：提升 formatVersionNumbers.PNG，并修复 images.Filter 的版本缓存失效问题（注意）d19e0a4b @bep #12536 #12543 #15266
  • warpc/js：将 katex 升级到 0.18.4（注意）ec52e638 @bep #15254
  • hexec：对逃逸 Node.js 权限路径的符号链接直接报错 c05c012a @bep
  • config/security：默认拒绝 text/org 内容 e6abb9c3 @bep
  • config/security：新增 http.proxyFromEnvironment，并说明解析地址检查 6a2a955d @bep #15301 #15302
  • deps：升级 github.com/gobwas/glob v0.2.3 => v1.0.0 efd24562 @bep #15273
  • hugofs：丢弃本身是符号链接的挂载根目录 938c8206 @bep
  • tpl：改进模板中的 return 关键字 8405b802 @bep #15212
  • resources/page：不再让标题中的 “/” 拆分自动派生的 slug 39507d51 @ipince #4092 #3577 #5571 #4090

glob 模式

用于模块挂载（includeFiles、excludeFiles）、cascade 目标、segments、deployment 匹配器和 noVendor 等处的 glob 库已升级到 v1.0.0。这是匹配引擎的完全重写，修复了一长串正确性问题，但这也意味着某些模式的行为可能发生变化：

  • 格式错误的模式（例如未闭合的 {、空的 [] 字符类）现在会以语法错误失败，而不再被静默接受。
  • ** 匹配包括分隔符在内的任意字符序列，但它不是 shell 的 **/“globstar”：**/x 要求存在字面量 /，因此不匹配 x；a/**/b 也不匹配 a/b。如果两者都需要，请使用 {**/,}x。
  • \ 是转义字符，因此字面量反斜杠必须写成 \\。

如果某个过去能匹配的模式现在不再匹配（或反之），那它很可能依赖的是旧引擎中的一个 bug。

安全

  • text/org 内容现在默认被拒绝，因为 Org mode 的导出块和 @@html:...@@ 片段会不经转义地传递原始 HTML，使其成为与 text/html 相同的 XSS 风险点。包含 Org 内容的站点可通过 security.allowContent 重新启用。
  • 远程抓取（resources.GetRemote 等）现在在拨号时校验解析后的地址，并拒绝回环、私有、链路本地、CGNAT 及类似网段。这仅在默认 security.http.urls 允许列表下生效；如果你已自定义该列表，说明你已自行选择主机，因此该检查不再介入。来自 HTTP_PROXY/HTTPS_PROXY 的代理会向该检查隐藏目标地址，因此现在会被忽略，除非你设置 security.http.proxyFromEnvironment = true。
  • Node.js 工具（PostCSS、Tailwind CSS 等）现在如果在项目内部存在解析到允许读写根目录之外的符号链接，会在调用前直接失败。如果你有合法的链接，请将其目标添加到 security.node.permissions.allowRead。
  • 本身即为符号链接的挂载根目录（例如 themes/mytheme/assets -> /somewhere/else）现在会被丢弃。这填补了 themes/ 限制中的一个缺口；绝对路径的挂载 source 值仍然允许。

其他

  • 在 partial 之外的 {{ return <value> }} 现在会报错；此前它会被静默忽略。
  • 标题中包含 / 且没有显式 slug 的页面（例如 Watch/listen to this）现在会得到单个 URL 段（.../watch-listen-to-this/），而不是嵌套的段（.../watch/listen-to-this/）。分类法和术语页面不受影响。
  • Hugo 现在使用 Go 1.27 构建。

KaTeX

升级到 Hugo v0.166.0 时，使用 transform.ToMath 且将 output 选项设为 html 或 htmlAndMathml 的站点，必须将模板中引用的 KaTeX 样式表更新到 0.18.4 或更高版本。使用 0.16.21 等较旧的 CSS 版本会导致某些数学或化学表达式渲染不正确。

更新示例：

- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">

参见以下示例：

Bug 修复

  • tpl/strings：修复 replaceRE 在零宽断言下的问题 ae07063f @youdie006
  • common/hreflect：修复浮点数转整数溢出保护中的差一错误 5130d000 @youdie006
  • resources/images：修复透明色和调色板图像上的滤镜问题 77856683 @bep #12536 #12543
  • github：修复陈旧 issue 的工作流 efe5cbc7 @jmooring #15261
  • all：运行 modernize -fix ./… 7b5199fd @bep
  • commands：修复 config 命令中 lang 标志的描述 87260e4a @jmooring #15223
  • hugolib：修复同一路径下删除多个节点时的切片越界 panic 49dceb19 @bep #15207
  • hugolib：修复 ReadingTime 和 FuzzyWordCount 的计算 5e709925 @jmooring #15206

改进

  • js：新增 es2025 作为受支持的构建目标 857120b7 @bep #15307
  • hugofs：丢弃本身是符号链接的挂载根目录 938c8206 @bep
  • markup/highlight：在传给 Chroma 之前转义 lineAnchors 3b2d3b82 @bep
  • tpl/partials：略微提升常见 partialCached 场景的性能 9c2527f8 @bep
  • 新增 internalExternal.IgnoreTailwindCSSSecurityError 配置项 a36bd274 @bep
  • config/security：加固默认 http.urls 与解析地址检查（#15285）24d5e42f @bep
  • resources/images：几何滤镜链保留源调色板 9e7c978e @bep #12543
  • resources/images：为调色板图像上的几何滤镜链新增 golden 测试用例 6b5b7d82 @bep #12543
  • resources/images：新增一些 golden 测试用例 62e24b7e @bep #12536 #12543
  • related：加快索引创建 f61346ed @bep
  • related：为索引值新增 tokenize 选项 850f11c0 @jmooring #7515 #15199
  • resources/page：不再让标题中的 “/” 拆分自动派生的 slug 39507d51 @ipince #4092 #3577 #5571 #4090
  • config/allconfig：提升 hugo mod init 的健壮性 90fe5068 @jmooring #15253
  • tpl：按转义模式区分延迟模板 49835f8f @Soundcreates #15234
  • resources：在远程抓取时校验解析后的地址 d6e6f9e5 @bep #15247
  • markup：在默认渲染器中转义代码围栏的属性值 e4dc48cf @bep #15247
  • hugolib：让 .Render 接受可选的上下文参数 bcde8063 @bep #15077
  • modules/npm：让生成的工作区包为私有并使用稳定名称 df4ac348 @bep #15245
  • common/hstore：排序 map 值时保持读锁 166d3ee1 @Soundcreates #15237
  • metrics：改进模板指标时长的格式化 a25af7fa @Shiwang0-0 #15027
  • 移除重建测试函数中的注释 723579ff @bep
  • hugolib：新增若干快速渲染模式的集成测试 85ad5e48 @bep
  • 升级到 Go 1.27 e31ff547 @bep #15228
  • tpl：改进模板中的 return 关键字 8405b802 @bep #15212
  • page：为 Pages 新增 IndexOf 方法 bf05832d @Shiwang0-0 #13589
  • tpl/resources：新增 resources.Publish a05736cb @bep #15208
  • markup/pandoc：支持 pandoc 3.11 及更高版本 423e9cea @jmooring #15271 #15280

依赖更新

  • build(deps)：将 google.golang.org/grpc 从 1.83.1 提升到 1.83.2 3fbfd273 @dependabot[bot]
  • build(deps)：将 golang.org/x/sync 从 0.22.0 提升到 0.23.0 393de587 @dependabot[bot]
  • build(deps)：将 golang.org/x/mod 从 0.40.0 提升到 0.41.0 870f7464 @dependabot[bot]
  • build(deps)：将 github.com/getkin/kin-openapi 从 0.146.0 提升到 0.149.0 6152e22e @dependabot[bot]
  • build(deps)：提升 github.com/bits-and-blooms/bitset 5b6e7c23 @dependabot[bot]
  • build(deps)：将 github.com/bep/lazycache 从 0.8.1 提升到 0.9.0 dc03bb27 @dependabot[bot]
  • build(deps)：将 github.com/bep/tmc 从 0.6.0 提升到 0.7.0 701dd337 @dependabot[bot]
  • build(deps)：将 github.com/yuin/goldmark 从 1.8.5 提升到 1.8.6 b4062c84 @dependabot[bot]
  • build(deps)：将 golang.org/x/image 从 0.44.0 提升到 0.45.0 cdd16273 @dependabot[bot]
  • deps：升级 github.com/gobwas/glob v0.2.3 => v1.0.0 efd24562 @bep #15273
  • build(deps)：将 golang.org/x/mod 从 0.39.0 提升到 0.40.0 d4629682 @dependabot[bot]
  • build(deps)：将 github.com/tdewolff/minify/v2 从 2.24.16 提升到 2.24.17 fd5f7c6e @dependabot[bot]
  • build(deps)：将 github.com/gohugoio/httpcache 从 0.8.0 提升到 0.9.0 6b335176 @dependabot[bot]
  • build(deps)：将 google.golang.org/grpc 从 1.82.1 提升到 1.83.1 5f0d88b8 @dependabot[bot]
  • build(deps)：将 golang.org/x/tools 从 0.48.0 提升到 0.49.0 9171daeb @dependabot[bot]
  • build(deps)：将 software.sslmate.com/src/go-pkcs12 从 0.7.0 提升到 0.7.2 d1ee825b @dependabot[bot]

更新内容 （原始）

This release is mostly about hardening and bug fixes, but there are some notable changes:

  • .Render now takes an optional context argument: {{ .Render "view" $ctx }}, mirroring the partial API. This makes it possible to pass e.g. a dict to a content view. See #15077.
  • The return keyword in templates has been reimplemented. It now works in any template (not just partials) and can be used anywhere, e.g. inside if or range blocks. See #15212.
  • New resources.Publish template function and IndexOf method on Pages.
  • related config: new tokenize option for index values, and index creation is faster.
  • Several security fixes; see the notes below.

Note

  • tpl/transform: Bump fileCacheEntryVersion in transform.ToMath (note) 8d88b8b4 @bep #15267
  • resources/images: Bump formatVersionNumbers.PNG and fix version cache busting for images.Filter (note) d19e0a4b @bep #12536 #12543 #15266
  • warpc/js: Upgrade katex to 0.18.4 (note) ec52e638 @bep #15254
  • hexec: Fail on symlinks that escape the Node.js permission paths c05c012a @bep
  • config/security: Deny text/org content by default e6abb9c3 @bep
  • config/security: Add http.proxyFromEnvironment and document the resolved address check 6a2a955d @bep #15301 #15302
  • deps: Upgrade github.com/gobwas/glob v0.2.3 => v1.0.0 efd24562 @bep #15273
  • hugofs: Drop symlinked mount roots 938c8206 @bep
  • tpl: Improve the return keyword in templates 8405b802 @bep #15212
  • resources/page: Don’t let a title’s “/” split an auto-derived slug 39507d51 @ipince #4092 #3577 #5571 #4090

Glob patterns

The glob library used for e.g. module mounts (includeFiles, excludeFiles), cascade targets, segments, deployment matchers and noVendor has been upgraded to v1.0.0. This is a complete rewrite of the matching engine that fixes a long list of correctness bugs, but it also means that some patterns may behave differently:

  • Malformed patterns (e.g. an unclosed {, an empty [] class) now fail with a syntax error instead of being silently accepted.
  • ** matches any sequence of characters including separators, but it is not the **/ “globstar” of shells: **/x requires the literal / and does not match x, and a/**/b does not match a/b. Use {**/,}x if you need both.
  • \ is the escape character, so a literal backslash must be written as \\.

If a pattern that used to match no longer does (or vice versa), it was most likely relying on a bug in the old engine.

Security

  • text/org content is now denied by default, as Org mode’s export blocks and @@html:...@@ snippets pass raw HTML through unescaped, making it the same XSS sink as text/html. Sites with Org content can opt back in via security.allowContent.
  • Remote fetches (resources.GetRemote etc.) now validate the resolved address at dial time and reject loopback, private, link-local, CGNAT and similar ranges. This only applies under the default security.http.urls allowlist; if you have customized it, you have opted into your own hosts and the check stands down. Proxies from HTTP_PROXY/HTTPS_PROXY hide the destination address from this check and are now ignored unless you set security.http.proxyFromEnvironment = true.
  • Node.js tools (PostCSS, Tailwind CSS etc.) now fail before invocation if a symlink inside the project resolves outside the allowed read/write roots. If you have a legitimate link, add its target to security.node.permissions.allowRead.
  • Mount roots that are themselves symlinks (e.g. themes/mytheme/assets -> /somewhere/else) are now dropped. This closes a gap in the themes/ confinement; absolute mount source values are still allowed.

Other

  • {{ return <value> }} outside a partial is now an error; it was previously silently ignored.
  • A page without an explicit slug whose title contains a / (e.g. Watch/listen to this) now gets a single URL segment (.../watch-listen-to-this/) instead of a nested one (.../watch/listen-to-this/). Taxonomy and term pages are not affected.
  • Hugo is now built with Go 1.27.

KaTeX

When upgrading to Hugo v0.166.0, sites using transform.ToMath with the output option set to html or htmlAndMathml must update the KaTeX stylesheet referenced in their template(s) to version 0.18.4 or higher. Using older CSS versions like 0.16.21 will cause certain mathematical or chemical expressions to render incorrectly.

Example update:

- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">

See these examples:

Bug fixes

  • tpl/strings: Fix replaceRE with zero-width assertions ae07063f @youdie006
  • common/hreflect: Fix the off-by-one in the float to int overflow guards 5130d000 @youdie006
  • resources/images: Fix filters on transparent colors and paletted images 77856683 @bep #12536 #12543
  • github: Fix workflow for stale issues efe5cbc7 @jmooring #15261
  • all: Run modernize -fix ./… 7b5199fd @bep
  • commands: Fix lang flag description in config command 87260e4a @jmooring #15223
  • hugolib: Fix slice bounds panic when deleting multiple nodes at same path 49dceb19 @bep #15207
  • hugolib: Fix ReadingTime and FuzzyWordCount calculations 5e709925 @jmooring #15206

Improvements

  • js: Add es2025 as supported build target 857120b7 @bep #15307
  • hugofs: Drop symlinked mount roots 938c8206 @bep
  • markup/highlight: Escape lineAnchors before passing it to Chroma 3b2d3b82 @bep
  • tpl/partials: Slight performance improvement of the common partialCached case 9c2527f8 @bep
  • Add internalExternal.IgnoreTailwindCSSSecurityError config option a36bd274 @bep
  • config/security: Harden the default http.urls and resolved address checks (#15285) 24d5e42f @bep
  • resources/images: Preserve the source palette for geometric filter chains 9e7c978e @bep #12543
  • resources/images: Add golden test cases for geometric filter chains on paletted images 6b5b7d82 @bep #12543
  • resources/images: Add some golden test cases 62e24b7e @bep #12536 #12543
  • related: Speed up index creation f61346ed @bep
  • related: Add tokenize option for index values 850f11c0 @jmooring #7515 #15199
  • resources/page: Don’t let a title’s “/” split an auto-derived slug 39507d51 @ipince #4092 #3577 #5571 #4090
  • config/allconfig: Improve resilience of hugo mod init 90fe5068 @jmooring #15253
  • tpl: Separate deferred templates by escaping mode 49835f8f @Soundcreates #15234
  • resources: Validate the resolved address on remote fetches d6e6f9e5 @bep #15247
  • markup: Escape code-fence attribute values in the default renderer e4dc48cf @bep #15247
  • hugolib: Make .Render take an optional context argument bcde8063 @bep #15077
  • modules/npm: Make the generated workspace package private with a stable name df4ac348 @bep #15245
  • common/hstore: Keep read lock while sorting map values 166d3ee1 @Soundcreates #15237
  • metrics: Improve template metrics duration formatting a25af7fa @Shiwang0-0 #15027
  • Remove comments from rebuild test functions 723579ff @bep
  • hugolib: Add some fast render mode integration tests 85ad5e48 @bep
  • Upgrade to Go 1.27 e31ff547 @bep #15228
  • tpl: Improve the return keyword in templates 8405b802 @bep #15212
  • page: Add IndexOf method to Pages bf05832d @Shiwang0-0 #13589
  • tpl/resources: Add resources.Publish a05736cb @bep #15208
  • markup/pandoc: Support pandoc 3.11 and later 423e9cea @jmooring #15271 #15280

Dependency Updates

  • build(deps): bump google.golang.org/grpc from 1.83.1 to 1.83.2 3fbfd273 @dependabot[bot]
  • build(deps): bump golang.org/x/sync from 0.22.0 to 0.23.0 393de587 @dependabot[bot]
  • build(deps): bump golang.org/x/mod from 0.40.0 to 0.41.0 870f7464 @dependabot[bot]
  • build(deps): bump github.com/getkin/kin-openapi from 0.146.0 to 0.149.0 6152e22e @dependabot[bot]
  • build(deps): bump github.com/bits-and-blooms/bitset 5b6e7c23 @dependabot[bot]
  • build(deps): bump github.com/bep/lazycache from 0.8.1 to 0.9.0 dc03bb27 @dependabot[bot]
  • build(deps): bump github.com/bep/tmc from 0.6.0 to 0.7.0 701dd337 @dependabot[bot]
  • build(deps): bump github.com/yuin/goldmark from 1.8.5 to 1.8.6 b4062c84 @dependabot[bot]
  • build(deps): bump golang.org/x/image from 0.44.0 to 0.45.0 cdd16273 @dependabot[bot]
  • deps: Upgrade github.com/gobwas/glob v0.2.3 => v1.0.0 efd24562 @bep #15273
  • build(deps): bump golang.org/x/mod from 0.39.0 to 0.40.0 d4629682 @dependabot[bot]
  • build(deps): bump github.com/tdewolff/minify/v2 from 2.24.16 to 2.24.17 fd5f7c6e @dependabot[bot]
  • build(deps): bump github.com/gohugoio/httpcache from 0.8.0 to 0.9.0 6b335176 @dependabot[bot]
  • build(deps): bump google.golang.org/grpc from 1.82.1 to 1.83.1 5f0d88b8 @dependabot[bot]
  • build(deps): bump golang.org/x/tools from 0.48.0 to 0.49.0 9171daeb @dependabot[bot]
  • build(deps): bump software.sslmate.com/src/go-pkcs12 from 0.7.0 to 0.7.2 d1ee825b @dependabot[bot]

下载链接