# 输出格式配置
> 定义和调整输出格式，控制页面的渲染产物。
- 官方英文原文：https://gohugo.io/configuration/output-formats/
- 本页规范地址：https://hugozh.cn/configuration/output-formats/
- 最近更新：2026-10-02
- 最后提交：912b1d3 chore(site): 添加 static/CNAME（hugozh.cn），供 GitHub Pages 等平台绑定自定义域名
- 站点：Hugo 中文文档（https://hugozh.cn/）· 社区维护的非官方中文翻译，如有出入以官方英文原文为准

---
同一个页面可以输出任意多种格式。你可以定义任意数量的输出格式，只要每种格式最终解析到唯一的文件系统路径即可。默认配置的表格形式如下：

| 键名 | mediaType | weight | baseName | isHTML | isPlainText | noUgly | notAlternative | path | permalinkable | protocol | rel | root | ugly |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `html` | `text/html` | 10 | `index` | `true` | `false` | `false` | `false` | `''` | `true` | `''` | `canonical` | `false` | `false` |
| `rss` | `application/rss+xml` | 0 | `index` | `false` | `false` | `true` | `false` | `''` | `false` | `''` | `alternate` | `false` | `false` |
| `json` | `application/json` | 0 | `index` | `false` | `true` | `false` | `false` | `''` | `false` | `''` | `alternate` | `false` | `false` |
| `amp` | `text/html` | 0 | `index` | `true` | `false` | `false` | `false` | `amp` | `true` | `''` | `amphtml` | `false` | `false` |
| `calendar` | `text/calendar` | 0 | `index` | `false` | `true` | `false` | `false` | `''` | `false` | `webcal://` | `alternate` | `false` | `false` |
| `css` | `text/css` | 0 | `styles` | `false` | `true` | `false` | `true` | `''` | `false` | `''` | `stylesheet` | `false` | `false` |
| `csv` | `text/csv` | 0 | `index` | `false` | `true` | `false` | `false` | `''` | `false` | `''` | `alternate` | `false` | `false` |
| `markdown` | `text/markdown` | 0 | `index` | `false` | `true` | `false` | `false` | `''` | `false` | `''` | `alternate` | `false` | `false` |
| `robots` | `text/plain` | 0 | `robots` | `false` | `true` | `false` | `false` | `''` | `false` | `''` | `alternate` | `true` | `false` |
| `sitemap` | `application/xml` | 0 | `sitemap` | `false` | `false` | `false` | `false` | `''` | `false` | `''` | `sitemap` | `false` | `true` |
| `sitemapindex` | `application/xml` | 0 | `sitemap` | `false` | `false` | `false` | `false` | `''` | `false` | `''` | `sitemap` | `true` | `true` |
| `webappmanifest` | `application/manifest+json` | 0 | `manifest` | `false` | `true` | `false` | `true` | `''` | `false` | `''` | `manifest` | `false` | `false` |

`weight`、`rel`、`baseName`、`path` 取值为空的项，其含义与上文字段说明中的默认行为一致。下面是与上表对应的部分默认配置片段：

```toml
[outputFormats.html]
baseName = 'index'
isHTML = true
isPlainText = false
mediaType = 'text/html'
notAlternative = false
path = ''
permalinkable = true
protocol = ''
rel = ''
root = false
ugly = false
weight = 10

[outputFormats.rss]
baseName = 'index'
isHTML = false
isPlainText = false
mediaType = 'application/rss+xml'
notAlternative = false
path = ''
permalinkable = false
protocol = ''
rel = 'alternate'
root = false
ugly = false
weight = 0
```

## 字段说明

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `baseName` | `string` | `index` | 发布文件的基础名。 |
| `isHTML` | `bool` | `false` | 是否把该输出格式归类为 HTML。它决定 LiveReload 脚本何时注入，并与 `permalinkable` 一起决定是否生成别名重定向。 |
| `isPlainText` | `bool` | `false` | 是否用 Go 的 `text/template` 包而非 `html/template` 包解析该格式的模板。 |
| `mediaType` | `string` | — | 发布文件的媒体类型，必须与已配置的媒体类型之一匹配。 |
| `notAlternative` | `bool` | `false` | 是否把该输出格式排除在 `Page` 对象的 `AlternativeOutputFormats` 方法返回值之外。 |
| `noUgly` | `bool` | `false` | 当项目配置启用了 `uglyURLs` 时，是否对该输出格式禁用丑 URL。 |
| `path` | `string` | — | 该输出格式发布路径的第一段，相对于 `publishDir` 根目录。省略时 Hugo 使用文件原本的内容路径发布。 |
| `permalinkable` | `bool` | `false` | 调用 `Page` 对象的 `Permalink` 与 `RelPermalink` 方法时，是否返回当前渲染格式而非主输出格式。与 `isHTML` 同为 `true` 时才会创建别名重定向。`html` 和 `amp` 默认启用。 |
| `protocol` | `string` | `baseURL` 的协议 | 该输出格式 URL 的协议（scheme），例如 `https://` 或 `webcal://`。默认取项目配置中 `baseURL` 的 scheme，通常是 `https://`。 |
| `rel` | `string` | `canonical` / `alternate` | 输出格式与当前页面的关系，Hugo 用它确定当前页面的规范输出格式。预定义 `html` 格式默认为 `canonical`，其他预定义格式默认为 `alternate`。 |
| `root` | `bool` | `false` | 是否把文件发布到发布目录的根目录。 |
| `ugly` | `bool` | `false` | 当项目配置中 `uglyURLs` 为 `false` 时，是否对该输出格式启用丑 URL。 |
| `weight` | `int` | `0` | 非零时作为输出格式排序的首要依据，其次才按格式名排序。数值小者靠前，大者靠后。Hugo 按排序结果依次渲染各输出格式。`html` 输出格式的默认权重为 `10`，其他为 `0`。 |

## 修改输出格式

任何默认输出格式都可以修改。例如要让 `json` 先于 `html` 渲染：

```toml
[outputFormats.json]
weight = 1
[outputFormats.html]
weight = 2
```

可见修改默认输出格式时，只需要写出与默认值不同的属性。

## 新建输出格式

以 Atom feed 为例，分四步：

第一步，输出格式必须指定媒体类型。Atom 使用 `application/atom+xml`，它不属于默认媒体类型，需要先创建：

```toml
[mediaTypes.'application/atom+xml']
suffixes = ['atom']
```

第二步，创建输出格式：

```toml
[outputFormats.atom]
mediaType = 'application/atom+xml'
noUgly = true
```

其余属性沿用默认值。

第三步，指定要为哪些页面种类渲染该格式：

```toml
[outputs]
home = ['html', 'rss', 'atom']
section = ['html', 'rss', 'atom']
taxonomy = ['html', 'rss', 'atom']
term = ['html', 'rss', 'atom']
```

第四步，创建模板。Atom feed 属于列表，需要创建列表模板，路径为：

```text
layouts/list.atom.atom
```

## 列出输出格式

每个 `Page` 对象提供两个方法：`OutputFormats`（包含当前格式在内的全部格式）与 `AlternativeOutputFormats`。用后者可以在 `head` 元素中生成 `rel` 链接列表：

```go-html-template
{{ range .AlternativeOutputFormats }}
  <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end }}
```

## 链接到输出格式

`Page` 对象的 `Permalink` 与 `RelPermalink` 方法返回的 URL 取决于当前输出格式。对于 `permalinkable` 为 `true` 的格式（如 `html` 和 `amp`），方法返回该格式自身的 URL；对其他格式，则返回页面主输出格式的 URL。

例如在 `page.json.json` 中：

```go-html-template
{{ .RelPermalink }} → /that-page/
{{ with .OutputFormats.Get "json" }}
  {{ .RelPermalink }} → /that-page/index.json
{{ end }}
```

若要让这些方法返回**当前**模板输出格式的 URL，必须把该格式的 `permalinkable` 设为 `true`。在同一个 `page.json.json` 模板中为 `json` 启用后：

```go-html-template
{{ .RelPermalink }} → /that-page/index.json
{{ with .OutputFormats.Get "html" }}
  {{ .RelPermalink }} → /that-page/
{{ end }}
```

## 模板查找顺序

每种输出格式都需要一个符合模板查找顺序的模板。文件名的具体形式为 `[页面种类].[输出格式].[后缀]`，例如对 section 页面：

| 输出格式 | 模板路径 |
| --- | --- |
| `html` | `layouts/section.html.html` |
| `json` | `layouts/section.json.json` |
| `rss` | `layouts/section.rss.xml` |