RSS 订阅
控制订阅源的生成范围与条数,在页面里引用订阅源,或编写自定义 RSS 模板;含产物核对方法与常见坑。
开始之前,你需要
- 站点能正常构建,并且有一个列表页(首页或 section)可以放内容。
- 会读 TOML 配置与模板里的动作语法(见简介)。
读完之后你能
- 说出默认为哪些页面种类生成订阅源,以及如何按页面种类关闭;
- 用
[services.rss] limit限制条目数,并在产物里数一数条目是否真的变少了; - 在页面
head里加上正确的订阅源<link>,并知道为什么要判空; - 需要改订阅源结构时,知道该创建哪些文件名(如
home.rss.xml)。
这一页解决什么问题
RSS 订阅源让读者用阅读器追更,也让聚合服务能抓取站点更新。Hugo 默认就会生成它,所以真正要处理的问题只有三个:
- 要不要生成——哪些页面种类需要订阅源;
- 生成多少条——不限制时,订阅源会随着站点增长越来越大(本站曾达到 2.1 MB,后来限流到 50 条);
- 页面里怎么声明——在
head里放一个指向订阅源的<link>,阅读器才能自动发现它。
配置
默认情况下,构建项目时 Hugo 会为**首页、section、分类法(taxonomy)与分类法条目(term)**页面生成 RSS 订阅源。生成范围由项目配置中的 [outputs] 决定。例如,只为首页和 section 页面生成,而不为分类法与条目页面生成:
[outputs]
home = ['html', 'rss']
section = ['html', 'rss']
taxonomy = ['html']
term = ['html']要彻底关闭所有页面类型的订阅源生成:
disableKinds = ['rss'][outputs] 是按页面种类逐个列出输出格式的白名单:写成 taxonomy = ['html'] 表示「分类法页面只要 HTML」,这一条比在别处写一堆开关都直观。改完配置后记得重启 hugo server。
条数限制
默认情况下,每个订阅源中的条目数量不限。可以按需要在项目配置中修改:
[services.rss]
limit = 42把 limit 设为 -1 表示每个订阅源的条目数不设上限。条数较少时订阅源文件更小,抓取端也更省流量。
内建的 RSS 模板还会读取项目配置中的以下值(如果设置了的话)并渲染进订阅源:
copyright = '© 2023 ABC Widgets, Inc.'
[params.author]
name = 'John Doe'
email = 'jdoe@example.org'结果长什么样
构建后(hugo),首页的订阅源是 public/index.xml,section 的订阅源是 public/<section>/index.xml。内建模板的输出结构如下(节选,来自本站的实际构建产物,值已替换为示例值):
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>ABC Widgets</title>
<link>https://example.org/</link>
<description>Recent content on ABC Widgets</description>
<generator>Hugo</generator>
<language>zh-CN</language>
<lastBuildDate>Fri, 02 Oct 2026 03:23:59 +0800</lastBuildDate>
<atom:link href="https://example.org/index.xml" rel="self" type="application/rss+xml" />
<item>
<title>Hello</title>
<link>https://example.org/posts/hello/</link>
<pubDate>Fri, 02 Oct 2026 00:00:00 +0800</pubDate>
<guid>https://example.org/posts/hello/</guid>
<description><p>页面正文的 HTML,转义后放进 description</p></description>
</item>
</channel>
</rss>两点值得留意:
<link>、<guid>、<atom:link>都是绝对地址,来自baseURL;<description>里是转义后的 HTML(<p>),这是 XML 的正常要求,不是出错。
验证标准
- 构建:
hugo; - 确认
public/index.xml存在;如果没生成,先检查是不是有页面种类被disableKinds关掉了; - 数一数
<item>的个数:不超过limit配置值(例如limit = 42时最多 42 条); - 用本地服务器看一遍更接近真实场景:
hugo server后访问http://localhost:1313/index.xml,浏览器应当显示 XML 源码,而不是站点的 404 页面。
在页面中引用订阅源
要在渲染出的页面 head 元素中加入订阅源引用,把下面这段放进模板的 head 元素内:
{{ with .OutputFormats.Get "rss" }}
{{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink site.Title | safeHTML }}
{{ end }}Hugo 会把它渲染成:
<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets">用 .OutputFormats.Get "rss" 判断当前页面是否配置了 RSS 输出,只有存在时才输出链接,可以避免为没有订阅源的页面生成空标签。注意 .Permalink 是绝对地址(阅读器要求如此),而 type 取的是 .MediaType.Type,即 application/rss+xml。
自定义模板
创建自己的 RSS 模板即可覆盖 Hugo 的内建模板。例如,为首页、section、分类法、条目页面分别使用不同的模板:
layouts/
├── home.rss.xml
├── section.rss.xml
├── taxonomy.rss.xml
└── term.rss.xml文件名由「页面类型 + 输出格式」组成,rss 对应 RSS 输出格式,因此可以针对不同页面类型给出不同的订阅源结构。RSS 模板的上下文中可以访问 .Page 和 .Site 对象。
只想改一份时不必写四份:只创建 layouts/home.rss.xml,其余页面种类仍会用内建模板。
最小可运行示例与验证
在 layouts/home.rss.xml 里写一份「只有标题和链接」的极简订阅源,最容易看出模板有没有被选中:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0">
<channel>
<title>{{ site.Title }}</title>
<link>{{ .Permalink }}</link>
{{ range .RegularPages }}
<item>
<title>{{ .Title }}</title>
<link>{{ .Permalink }}</link>
</item>
{{ end }}
</channel>
</rss>构建后打开 public/index.xml,你应当看到 <rss version="2.0"> 后面没有 xmlns:atom 等内建模板才有的属性——这就证明自定义模板确实生效了。(如果内容与原来一样,说明文件名没写对,对照模板查找顺序检查。)
常见坑
| 类别 | 现象 | 原因与处理 |
|---|---|---|
| 命令找不到 | hugo: command not found / 「不是内部或外部命令」 |
Hugo 没装或没进 PATH → 安装 Hugo |
| 没报错但结果不对 | public/index.xml 没有生成 |
disableKinds 里有 'rss',或 [outputs].home 没写 'rss' → 对照本页配置示例 |
| 没报错但结果不对 | 订阅源里的文章标题、正文是旧内容 | 阅读器或浏览器缓存;也可能 limit 太小导致目标文章不在窗口内 → 用无痕窗口访问 /index.xml 复核 |
| 没报错但结果不对 | 订阅源文件特别大(几 MB) | 没有设置 [services.rss] limit → 设置一个合理上限(如 50)并重新构建 |
| 报错看不懂 | 修改 [outputs] 后构建出现 found no layout file for … 警告 |
打开了某个输出格式却没有对应模板,Hugo 会回退内建模板;若是自定义输出格式则需自备模板 → 见输出格式 |
| 报错看不懂 | 构建时报模板执行失败,行号指向 layouts/home.rss.xml |
自定义 RSS 模板动作没闭合,或 XML 中出现了非法字符 → 用 hugo --renderToMemory 复现,按报错行号定位 |
更多排查入口见故障排查。