Hugo 深入解析：canonical output format（规范化输出格式）的判定规则与模板用法

• 开发工具
• 前端
• CLI

canonical output format 是 Hugo 多格式输出体系中的一个关键概念，它决定了一个页面在多种输出格式（如html、amp、json、rss）中"哪个才是规范版本"，进而影响<link rel="canonical">等 SEO 关键标签的生成。本文以 Hugo 官方词汇表文档 canonical-output-format.md 为核心骨架，结合仓库源码与实际测试用例，完整梳理其定义、判定规则、默认行为，并给出可在模板中直接落地的OutputFormats.Canonical用法，帮助你在多格式站点中正确控制规范 URL。

什么是 canonical output format

canonical output format（规范化输出格式）是当前页面的 output format 中，被认定为"规范表示"的那一个格式。简单地说：当一个页面同时渲染出 HTML、AMP、JSON、RSS 等多个版本时，Hugo 需要从中选出一个作为权威版本，这个被选中的格式就是 canonical output format。

它在实际站点中的典型落点是一个link标签：

<link rel="canonical" href="https://example.org/that-page/">

以 sitematrix_integration_test.go 中的断言为例，同一个页面同时输出public/index.html与public/amp/index.html时，AMP 版本的 HTML 中会写入指向 HTML 规范版本的 canonical 链接：

<link rel="canonical" href="https://example.org/guest/v1.0.0/en/">

判定规则一：rel属性显式设为canonical

按照词汇表文档的定义，canonical output format 的第一种判定方式是：当前页面的某个 output format，其rel属性在项目配置中被显式设置为canonical（前提是存在这样的格式）。

rel是 output format 定义中的一个配置项，用于描述该格式与当前页面的关系。Hugo 官方配置文档对其说明如下：

rel（string）：输出格式与当前页面的关系。Hugo 使用此属性来确定当前页面的 canonical output format。对于预定义的html输出格式，默认值为canonical；对于所有其他预定义输出格式，默认值为alternate。

（参见 output-formats.md）

也就是说，rel的取值直接参与了 canonical 的判定。当你查看内置格式的定义时，可以看到这一约定的具体落地：outputFormat.go 中定义了全部内置输出格式，其中：

• HTMLFormat的Rel: "canonical"（见 outputFormat.go）；
• AMPFormat的Rel: "amphtml"，用于 AMP 页面相互发现；
• CalendarFormat、CSVFormat、JSONFormat、MarkdownFormat、RSSFormat、RobotsTxtFormat等绝大多数格式的Rel均为"alternate"；
• CSSFormat的Rel: "stylesheet"、SitemapFormat的Rel: "sitemap"等则各有语义用途。

内置格式中，html是唯一一个默认rel为canonical的预定义格式。

判定规则二：单一预定义格式的自动豁免

词汇表文档指出了一条重要的补充规则：

如果当前页面只有一个output format，并且它是一个预定义格式，那么无论其rel属性是否被设置为canonical，Hugo 都会自动将其视为 canonical output format。自定义输出格式不适用此规则，rel必须被显式设置为canonical。

这条"豁免"逻辑在源码中有明确实现。page_outputformat.go 的NewOutputFormat构造函数：

func NewOutputFormat(relPermalink, permalink string, isCanonical bool, f output.Format) OutputFormat { isUserConfigured := true for _, d := range output.DefaultFormats { if strings.EqualFold(d.Name, f.Name) { isUserConfigured = false } } rel := f.Rel // If the output format is the canonical format for the content, we want // to specify this in the "rel" attribute of an HTML "link" element. // However, for custom output formats, we don't want to surprise users by // overwriting "rel" if isCanonical && !isUserConfigured { rel = "canonical" } return OutputFormat{Rel: rel, Format: f, relPermalink: relPermalink, permalink: permalink} }

这里有两个关键点：

1. 只有isCanonical为真且格式为预定义格式（isUserConfigured == false）时，rel才会被强制改写为"canonical"；
2. 自定义格式即使isCanonical为真也不会被改写，以此避免"意外惊喜"——这是文档中"自定义格式不适用该规则"的源码依据。

而isCanonical这个布尔值在调用处由"页面输出格式的数量是否等于 1"决定，见 page__paths.go：

pageOutputFormats[i] = page.NewOutputFormat(relPermalink, permalink, len(outputFormats) == 1, f)

即：len(outputFormats) == 1时，isCanonical为true。这解释了"只有一个输出格式时自动成为 canonical"的行为。

判定规则三：多个 canonical 并存时的优先级

如果当前页面有两个或更多output format 的rel都被设置为canonical，Hugo 会选取最先出现的那一个。而这个"顺序"由以下两处决定：

1. 当前页面 front matter 中的outputs字段（按页面指定）；
2. 项目配置中针对当前 page kind 的outputs配置段（按页面类型指定）。

也就是说，outputs列表中的顺序就是 canonical 的裁决顺序。这也与"primary output format 是outputs列表中的第一个元素"的规则（见 outputs.md 与词汇表 primary-output-format.md）相呼应——虽然 primary 与 canonical 是两个不同的概念（前者决定Permalink/RelPermalink的取值，后者决定规范版本），但二者都依赖outputs列表的顺序。

OutputFormats.Canonical()方法则从结果侧印证了这一顺序语义，见 page_outputformat.go：

// Canonical returns the first canonical OutputFormat for this page, // or a zero OutputFormat if not found. func (o OutputFormats) Canonical() OutputFormat { const canonical = "canonical" for _, f := range o { if strings.EqualFold(f.Rel, canonical) { return f } } return OutputFormat{} }

它按列表顺序线性扫描、返回第一个rel为canonical（大小写不敏感）的格式；如果没有找到，则返回零值OutputFormat。

在模板中使用：OutputFormats.Canonical方法

从 Hugo 0.154.4 起，Page.OutputFormats提供了Canonical方法，可以直接获取当前页面的 canonical output format。官方方法文档 OutputFormats.md 给出了完整示例：

{{ with .Site.Home.OutputFormats.Canonical }} {{ .MediaType.Type }} → text/html {{ .MediaType.MainType }} → text {{ .MediaType.SubType }} → html {{ .Name }} → html {{ .Permalink }} → https://example.org/ {{ .Rel }} → canonical {{ .RelPermalink }} → / {{ end }}

需要说明的是，该示例输出是在默认配置下的结果：此时html是首页唯一的 canonical 格式，因此各项属性均指向 HTML 版本。若页面配置了多个 canonical 格式，取到的将是按上文规则裁决出的第一个。

要在页面<head>中渲染指向规范版本的link标签，官方推荐写法如下：

{{ with .OutputFormats.Canonical }} {{ printf "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }} {{ end }}

Canonical方法返回的是page.OutputFormat对象，可继续调用其关联方法（Name、MediaType、Permalink、RelPermalink、Rel等）；与之配套的OutputFormats.Get则按标识符（如"rss"）精确获取某个格式：

{{ with .OutputFormats.Get "rss" }} <a href="{{ .RelPermalink }}">RSS Feed</a> {{ end }}

内置 alias 模板中的 canonical 应用

canonical output format 不仅服务于页面模板，还深度参与了 Hugo 的别名（alias）重定向机制。Hugo 在生成 301/302 别名跳转页时，会在跳转页的<head>中同时写入 canonical 链接，其内置模板 alias.html 如下：

<!DOCTYPE html> <html lang="{{ site.Language.Locale }}"> <head> <title>{{ .Permalink }}</title> {{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }} <meta charset="utf-8"> <meta http-equiv="refresh" content="0; url={{ .Permalink }}"> </head> </html>

这里的with .OutputFormats.Canonical正是利用上述判定逻辑：仅当页面存在 canonical 格式时才输出<link rel="canonical">。对应的集成测试 alias_test.go 断言了实际产物：

<link rel="canonical" href="https://example.org/foo/s1/"> <meta http-equiv="refresh" content="0; url=https://example.org/foo/s1/">

实战验证：自定义格式不会抢占 canonical

下面用一个仓库中现成的集成测试来说明上述全部规则的实际效果。outputFormat_integration_test.go 的TestCanonical：

# hugo.toml [outputs] home = ["notcanonical", "html", "rss"] [outputFormats] [outputFormats.notcanonical] mediaType = 'text/html' path = 'not' isHTML = true

{{/* layouts/all.html */}} All. Canonical: {{ .OutputFormats.Canonical.RelPermalink }}.

配置解读：

• 首页被指定渲染notcanonical、html、rss三个格式；
• notcanonical是自定义格式，其定义中没有设置rel（默认不满足"显式rel: canonical"），因此尽管它排在outputs列表的第一位，也不能成为 canonical；
• html是预定义格式且默认rel: "canonical"，于是被裁决为 canonical。

测试断言了两处产物的输出内容：

b.AssertFileContent("public/not/index.html", "All. Canonical: /.") b.AssertFileContent("public/index.html", "All. Canonical: /.")

notcanonical渲染出的页面与 HTML 页面中，Canonical.RelPermalink都指向/（即 HTML 版本），直观验证了"自定义格式必须显式设置rel: canonical才可能成为规范格式"的规则。

常见问题与注意事项

• 不要把 canonical 与 primary output format 混为一谈：primary output format 是outputs列表的第一个元素，决定Page.Permalink/RelPermalink的默认取值；canonical output format 则是rel: canonical的裁决结果。默认配置下二者通常都是html，但通过自定义配置可以拆分（例如outputs第一个是自定义格式时，primary 随之改变，而 canonical 仍可能是html）。
• outputs数组顺序很重要：官方配置文档明确提示"数组中的顺序很重要"，第一个元素将成为该 page kind 的 primary output format，且 canonical 冲突时按该顺序取第一个。参见 outputs.md。
• 自定义格式的rel不会被自动改写：即使页面只有这一个自定义格式，Hugo 也不会将其rel强制为canonical，必须显式配置rel = 'canonical'。
• 找不到 canonical 时方法返回零值：OutputFormats.Canonical()在没有命中时返回零值OutputFormat，模板中请始终配合with使用，避免输出空标签。
• rel比较大小写不敏感：源码中使用strings.EqualFold(f.Rel, canonical)进行匹配（见 page_outputformat.go），配置时写canonical、Canonical均能命中。

小结

canonical output format 是 Hugo 多格式输出体系中控制"规范版本"的核心机制，其判定遵循三条规则：显式rel: canonical、单一预定义格式自动豁免、多个 canonical 按outputs列表顺序取第一个。理解并善用OutputFormats.Canonical方法，你可以精确控制站点中<link rel="canonical">的输出，确保多格式、多语言场景下的 SEO 权威 URL 指向正确，同时借助仓库内置模板与集成测试（alias.html、outputFormat_integration_test.go）在实际项目中验证行为。

• 开发工具
• 前端
• CLI