写博客的人大概都有过这种体验：列表页上的文章摘要忽长忽短，有的直接显示了半篇正文，有的只剩一个标题，有时候首页还能看到没闭合的 HTML 标签。我自己刚开始折腾 Hugo 那阵，为了让首页文章列表好看一点，试过truncate、plainify、safeHTML各种排列组合，最后才意识到，真正该搞懂的是 Hugo 原生提供的Page.Summary方法——它有一套自己的优先级规则：前置元数据里的 summary 字段、正文中的<!--more-->分隔符、都没写时自动截取前 N 个词。
这篇文章就把这套规则彻底讲透，再落到模板实战上。无论你是用现成主题想微调列表页，还是自己从零写 Hugo 模板，只要列表页需要展示摘要，这篇内容都能帮你省下不少调试时间。我会把三种摘要来源、优先级顺序、以及我实测过程中踩过的坑一起说清楚。
1. 摘要从哪里来：不止自动截取这一条路
1.1 自动摘要：最省事，也最不可控
自动摘要是 Hugo 的默认行为。每篇内容在渲染时，如果前面没有其他设置，Hugo 会从正文开头截取一段作为摘要。截取长度由站点配置里的summaryLength决定，默认是 70。注意这里的单位是"词"（word），不是字符。
这样的设计对英文站点很友好：英文单词天然有空格分隔，70 个单词大约相当于三四句话，作为索引页摘要刚好。但它的缺点也很明显，截断点不由你控制，完全可能落在句子的中间，读到一半突然断掉，体验非常割裂。
自动摘要的另一层特性是：即使你什么都没写，.Summary也一定有一个值。除非页面正文为空，否则摘要永远存在。这就意味着很多主题的列表页不需要你做任何配置就能跑起来，但也意味着它很难做到"每篇都刚好卡在你想展示的位置"。它适合文章量很大、不追求每篇精确展示、列表页只求整齐的场景。
1.2<!--more-->手动分隔符：把摘要边界握在自己手里
Hugo 最早引入的摘要控制方式，是在正文里插入<!--more-->这个 HTML 注释。比如这样：
--- title: "示例文章" --- 这是文章开头的导语，读者会在列表页看到这一部分。 <!--more--> 这里是正文的剩余内容，只有点进详情页才会看到。分隔符之前的内容会被当作.Summary，分隔符之后的内容只会在.Content完整输出时出现，也就是详情页里正常显示。而<!--more-->本身在渲染后会被移除，所以最终页面上不会出现任何残留标记。
这是我最推荐的一种方式。它跟正文待在一起，写文章的时候顺手就能打上，不需要额外维护一段摘要文案。只要你在开头习惯写一段可独立阅读的导语，那这个分隔符放的位置通常天然就是摘要的边界。
不过它也有个隐性前提：如果分隔符放在文章最开头，摘要就是空的；如果分隔符在末尾，摘要又等于全文。模板里遇到这两种情况需要额外处理，后面我会给兜底方案。
1.3 前置元数据 summary 字段：摘要和正文彻底分离
第三种方式是直接在 front matter 里声明 summary 字段：
--- title: "示例文章" summary: "这是我在前置元数据里指定的列表摘要，和正文内容没有直接关系。" ---这种方式的好处是摘要与正文彻底解耦。你可以写一段纯粹的引语、宣传文案，甚至把文章里的核心结论提炼成一句话放进去。它不受正文开头内容的限制，也不受summaryLength影响。
但它也有代价：每篇文章都要额外维护一个字段，容易写着写着就忘了。而且如果你偷懒不写，Hugo 会退回用其他的摘要方式，列表页展示效果就不一定是你想要的了。另一个问题是，列表页显示的摘要和你正文开头可能完全对不上，读者点击进去会有落差感。所以它更适合内容站点、产品介绍页，以及你确实愿意为每篇内容单独写摘要的场景。
三种来源放在一起对比，会更清楚：
| 摘要来源 | 触发条件 | 控制粒度 | 适用场景 | 主要风险 |
|---|---|---|---|---|
| 自动摘要 | 未写 summary、正文无分隔符 | 仅配置长度，断点随机 | 英文博客、海量文章 | 断句生硬，中文表现极差 |
<!--more--> | 正文中手动插入注释 | 摘要边界完全可控 | 导语型博客、常规技术文章 | 忘记插入时退回自动摘要 |
| front matter summary | 前置元数据声明字段 | 摘要与正文彻底分离 | 产品页、内容聚合、SEO 描述 | 维护成本高，容易漏写 |
2. 优先级顺序：front matter 最优，more 次之，自动兜底
2.1 先给结论：三级优先级从上往下走
Page.Summary的取值优先级非常明确，一句话就能说清：
front matter 里的
summary字段 > 正文里的<!--more-->分隔符 > 自动截取。
也就是说，即使你正文里放了<!--more-->，只要 front matter 里写了summary，.Summary输出的就是前端元数据里的内容。同样的，如果前两种都没有，才轮到自动截取。
这个优先级从 Hugo 源码层面也解释得通。Hugo 在构建页面对象时，会先检查Params.summary是否有值，有就直接采用；没有才进入正文摘要逻辑，而正文摘要逻辑又是先找<!--more-->分隔符，找不到再退到自动截断。所以这个行为不是某个主题魔改出来的，而是框架层面的固定机制。
这里要特别强调一点：这个优先级只影响.Summary，不影响.Content。.Content永远输出完整正文，无论<!--more-->放在哪里，渲染出来的详情页内容都完整。所以你完全不用担心在正文里插入分隔符会让读者看不到后面的内容。
2.2 用一个最小例子验证优先级
如果你在自己站点里改了摘要相关配置，想确认到底哪个来源生效，其实可以做一组最小实验。我建议在本地新建一个测试页面，比如content/test-summary.md：
--- title: "摘要优先级测试" summary: "来自 front matter 的摘要" --- 这是 more 分隔符之前的内容。 <!--more--> 这是 more 分隔符之后的内容。然后在列表模板里输出.Summary，观察首页效果：
- 同时存在 front matter summary 和 more 分隔符时，页面上显示"来自 front matter 的摘要"。
- 把 front matter 里的 summary 字段删掉，保留 more 分隔符，页面上显示"这是 more 分隔符之前的内容"。
- 再把
<!--more-->也删掉，页面上显示的是正文开头的自动截取。
这个实验值得自己跑一遍，因为很多人在实际项目里是"三种方式混着用"的，比如旧文章里可能有分隔符，新文章里统一写了 summary 字段，最后发现列表页展示风格完全不统一，根因就是优先级没有吃透。
2.3 .Truncated 的返回值：谁决定它
.Truncated是另一个高频使用的页面属性，它表示摘要是否相对正文被截断了。很多人以为它是"该不该显示阅读全文"的开关，其实它会随摘要来源不同而有截然不同的表现：
- 使用 front matter summary 时，
.Truncated恒为false。因为 Hugo 认为你手动给了完整摘要，不存在"被截断"这件事。 - 使用
<!--more-->分隔符且分隔符后仍有内容时，.Truncated为true。 - 使用自动摘要且正文长度超过了
summaryLength配置时，.Truncated为true；如果正文本来就很短，没超过长度，则为false。
实战中最容易出现的问题是：你用了 front matter summary，但模板里只依赖.Truncated判断是否显示"阅读全文"链接，结果所有写了 summary 的文章都看不到这个链接。这不是 Hugo 出 bug 了，而是.Truncated在那个模式下本来就是 false。
我的处理方式是：如果某个区块就是想要"始终显示阅读全文"的按钮，不要只用.Truncated判断，可以改成这样：
{{ if (or .Truncated .Params.summary) }} <a class="read-more" href="{{ .RelPermalink }}">阅读全文</a> {{ end }}这样即使 front matter summary 不触发截断标志，只要确实写了 summary，一样会出现阅读入口。前提是你确认这些文章都有完整正文，否则空摘要文章也会多出一个多余链接，后面我们还会讲到空摘要的兜底。
3. 模板实战：列表页摘要卡片与“”的正确姿势
3.1 一份可以直接用的列表模板
弄清楚优先级之后，模板里的用法反而简单了。一个标准的列表页卡片长这样：
{{ range .Pages }} <article class="post-card"> <h2 class="post-card__title"> <a href="{{ .RelPermalink }}">{{ .Title }}</a> </h2> {{ if .Summary }} <div class="post-card__summary"> {{ .Summary }} </div> {{ end }} {{ if .Truncated }} <a class="post-card__more" href="{{ .RelPermalink }}">{{ i18n "readMore" | default "阅读全文" }}</a> {{ end }} </article> {{ end }}这里有几个细节值得说。.Summary返回的是template.HTML类型的安全 HTML，直接输出即可，千万不要在外面套一层safeHTML，那是多此一举。Hugo 在自动截断时会尽量保持标签闭合，输出相对干净。
第二个细节是链接地址用.RelPermalink而不是.Permalink。相对链接在本地调试和子路径部署时都更稳定，也不会因为域名切换导致全文链接失效。
第三个细节是卡片样式。摘要内容长短不可控，列表页又要求视觉整齐，我的经验是用 CSS 控制行数，而不是在模板层强行截断：
.post-card__summary { display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }这样即使某篇文章的摘要特别长，列表页也只会显示三行，超出部分优雅省略，不会把整个卡片撑得乱七八糟。
3.2 用 partial 封装摘要卡片，构建时还能缓存
当你有多个地方要展示文章列表时（首页、分类页、标签页、归档页），重复复制这段卡片模板显然不优雅。我习惯把它抽成一个 partial，放在layouts/partials/post-card.html：
<article class="post-card"> <h2 class="post-card__title"> <a href="{{ .RelPermalink }}">{{ .Title }}</a> </h2> <div class="post-card__summary"> {{ .Summary }} </div> {{ if .Truncated }} <a class="post-card__more" href="{{ .RelPermalink }}">{{ i18n "readMore" | default "阅读全文" }}</a> {{ end }} </article>调用的时候用一个 range 循环即可：
{{ range .Pages }} {{ partialCached "post-card.html" . .RelPermalink }} {{ end }}这里的partialCached是性能优化利器。普通partial每次调用都会重新渲染，而partialCached会按第三个参数作为 key 做缓存。用.RelPermalink当 key 非常合适，因为同一篇文章在多个列表中出现时，它的摘要内容是完全相同的，没必要重复渲染。
要注意的是，如果你修改了站点配置里和摘要相关的参数（比如summaryLength），旧的 partialCached 缓存可能不会自动失效。构建时加--gc参数清一次缓存就好：
hugo server --gc3.3 多语言主题里的“”链接
如果你的站点启用了多语言，摘要本身不用太担心，Hugo 会按当前语言渲染对应语言的内容，.Summary读取的是当前语言页面的摘要。真正需要注意的反而是 UI 文案。
"阅读全文"这类链接文案应该走 i18n，而不是硬编码中文。在i18n/en.toml、i18n/zh.toml里做对应翻译，模板中统一取：
{{ i18n "readMore" | default "阅读全文" }}这样英文版显示 Read more，中文版显示阅读全文，不需要在模板里做语言判断。
另外，不同区块可能需要不同风格的摘要展示。比如首页大图卡片摘要可以完整展示.Summary，侧栏小卡片只想要 80 字以内的紧凑文本。我的做法是给 partial 传参，而不是为每种长度单独写一个模板：
{{ partial "post-card.html" (dict "page" . "maxLen" 80) }}partial 内部这样控制：
{{ if .maxLen }} {{ .page.Summary | plainify | truncate .maxLen }} {{ else }} {{ .page.Summary }} {{ end }}truncate函数会按字符数截断，对中文相对友好。但注意这里的plainify会把摘要里的 HTML 标签全部去掉，适合侧栏这种"只要一行纯文本"的场景。如果你希望保留格式，直接输出原生.Summary就好。
4. 中文站点最容易踩的摘要坑：自动截断为什么失灵
4.1 摘要长度单位是“词”，中文整段可能只算一个词
这是 Hugo 摘要机制在中文站点里最经典的坑。前面说过，summaryLength默认 70，单位是"词"。Hugo 在做自动截断时，会先把正文按空白字符分词，再统计前 N 个词。
问题就出在这里：中文段落通常没有空格。一段三百字的中文，内部没有任何空白，分词器会把它整体当成一个"词"。于是默认的 70 词阈值对纯中文文章几乎不起作用，摘要要么等于正文开头一整段，严重时甚至等于整篇全文。
我实测过一篇 1500 字的中文长文，既没有 front matter summary，也没有<!--more-->，首页列表里直接把整篇文章都展示了出来，.Truncated返回false，"阅读全文"链接自然也没出现。这个现象在不同 Hugo 版本里可能略有差异，但整体表现非常一致，很多中文博客的首页布局不齐，根源往往就在这里。
解决办法有几个，按推荐程度排序：
- 使用
<!--more-->手动标记，把导语放在分隔符前，这是最稳定、最不依赖框架分词逻辑的方案。 - 在 front matter 里写 summary 字段，适合你本来就准备摘要文案的情况。
- 修改
summaryLength对纯中文基本无效，不用白费力气。 - 在模板层对未截断的短文章做兜底处理，下面会讲具体做法。
4.2 手动 summary 里的 HTML 会破坏列表页布局
第二个高频问题出在 front matter 的 summary 字段本身。很多人在 YAML 里写 summary 时顺手带上了 HTML 标签，比如：
summary: "<p>这是一段摘要</p>"由于.Summary返回的是安全 HTML，Hugo 不会帮你重新清洗标签，页面输出时这个<p>标签就会原样出现。如果摘要卡片外层本身已经包裹了<div class="post-card__summary">，再套一个块级标签进来，布局就可能错乱，样式也会受影响。
我的建议是：front matter 里的 summary 字段只写纯文本，不要写块级标签，也不要依赖 Markdown 语法加粗、链接之类的效果。它会以字面文本的形式直接输出到列表页，想要复杂格式，请把内容放到正文里，用<!--more-->控制摘要。如果确实需要在模板层统一清洗，可以对.Summary做一次plainify：
{{ .Summary | plainify }}这样输出的是纯文本，安全，但格式也没了。这是个取舍，看你的页面设计需要什么。
4.3 summaryLength 配置到底管什么
summaryLength是 Hugo 站点配置里的根级参数，写在 hugo.toml 中可以这样配：
summaryLength = 120它只影响自动摘要的长度，默认值是 70，单位是词。对英文博客来说，调到 120 或 150 能让列表摘要更完整，减少"一句话没读完就被截断"的情况。对中英混排的文章也有一定效果，因为英文单词和数字部分可以被正常分词。
但回到中文场景，这个配置很容易被误解。如果你把summaryLength从 70 改成 500，看起来是放宽了摘要长度，但由于中文整段被当成一个词，500 这个阈值依然不会被触发，摘要还是全文。所以这个参数对纯中文内容基本没有意义，真正解决问题还得靠分隔符或 front matter summary。
另外提醒一句：Hugo 没有官方的 per-pagesummaryLength覆写功能，不要在 front matter 里试图给单篇文章单独设置摘要长度，至少我测试过的版本都没有可靠支持。与其和框架较劲，不如老老实实用<!--more-->。
4.4 短文章与空摘要：列表页出现整篇正文的兜底处理
短文章是另一个容易翻车的情况。一篇只有两百字的短文，如果没有 summary 和分隔符，自动摘要把全文都算进去了，.Truncated返回false，整个列表页就会直接显示这篇短文的全部内容。对于内容聚合型站点，这会让首页显得很杂乱。
我常用的兜底逻辑是在列表模板里根据.WordCount做判断。.WordCount也是 Hugo 页面对象的一个属性，统计正文词数。对短文章，列表页只保留标题和日期，不展示摘要：
{{ if gt .WordCount 120 }} <div class="post-card__summary">{{ .Summary }}</div> {{ end }}120 这个阈值可以根据你的内容风格调整，目的是保证过短的文章不会在列表页"裸奔"。
空摘要的情况也要考虑。用<!--more-->且在正文前没有内容时，.Summary就是空字符串，模板里如果直接输出会留下空白卡片。所以在输出摘要前，我习惯加一个判断：
{{ if .Summary }} <div class="post-card__summary">{{ .Summary }}</div> {{ end }}如果摘要为空，整个卡片就只显示标题和元信息，视觉效果依然完整，不会出现一块空洞。
5. 摘要的延伸：SEO 描述、RSS 输出与自定义截断
5.1 把 .Summary 变成干净的 meta description
列表页摘要不只用于展示，它还是 SEO meta description 的理想数据源。不过 meta 标签里不能有 HTML，所以不能直接输出.Summary，需要先plainify再截断。
我通常的做法是优先使用 front matter 里的description字段，没写的时候才从摘要兜底：
{{ $desc := .Description | default (.Summary | plainify | truncate 160) }} <meta name="description" content="{{ $desc }}">这里truncate 160是 160 个字符，对中文搜索结果显示比较友好。如果你更看重 SEO 的统一控制，可以约定每篇文章都写description字段，然后把.Summary完全用在列表展示上，两个数据源互不干扰。这是最清晰的分工。
5.2 RSS 输出全文还是摘要：一个容易忽略的取舍
Hugo 内置的 RSS 模板默认输出全文，也就是.Content。用户订阅之后，在阅读器里就能看到完整文章。这是很多内容创作者喜欢的模式，因为它对读者最友好，也方便全文归档。
但如果你希望引导订阅用户回到站点阅读、互动，把 RSS 改成只输出摘要会更合适。自定义 RSS 模板时，在layouts/_default/rss.xml里把 description 字段改为摘要即可：
<description>{{ .Summary | html }}</description>这里用html过滤器把摘要里的 HTML 转义为实体，保证 RSS XML 结构不损坏。大多数阅读器都优先读取 description 字段，如果里面只有摘要，用户看完摘要就会点链接进站。到底用全文还是摘要，取决于你的内容分发策略，没有对错，但值得明确决策，而不是让模板默认行为替你选。
5.3 不满足于原生摘要时，自己再做一层截断
有时候原生摘要机制已经生效了，但你还是想在某些特殊区块显示更短的文本。比如首页的特色推荐位，或者移动端的小卡片，摘要只想显示 60 个字。这种场景可以基于.Summary再做一次处理：
{{ .Summary | plainify | truncate 60 }}truncate函数按字符数截断，对中文相对公平。但要注意，这一步会丢掉所有格式。如果你的卡片只放纯文本，这是最简单的方案。
也有人想保留格式又限长，比如只保留加粗、链接这些行内标签。这需要用 HTML 解析器做标签感知的截断，Hugo 模板语言本身没有提供这么精细的函数。说实话我不建议在模板层硬做，维护成本高，效果也未必好。我在实际项目里的习惯是：主列表用原生.Summary，侧栏或推荐位用plainify + truncate的纯文本方案，两类区域分开样式设计，各管各的，反而干净。
页面摘要这件事，放在整个站点的技术栈里确实不起眼，但它直接影响首页信息密度和点击率。我的个人习惯是：每篇文章开头都会写一段可以独立阅读的导语，然后在导语结尾放<!--more-->；front matter 里的summary字段只用于 SEO 描述，不在列表页重复展示；列表模板里始终保留.Truncated判断，同时清楚这个判断只对 more 和自动截断两种模式有意义。如果你也想给站点做一次体验升级，不妨先从列表页的摘要开始，这个投入产出比往往比换主题、改配色来得更直接。
