写博客的人大概都有过这种体验列表页上的文章摘要忽长忽短有的直接显示了半篇正文有的只剩一个标题有时候首页还能看到没闭合的 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 classread-more href{{ .RelPermalink }}阅读全文/a {{ end }}这样即使 front matter summary 不触发截断标志只要确实写了 summary一样会出现阅读入口。前提是你确认这些文章都有完整正文否则空摘要文章也会多出一个多余链接后面我们还会讲到空摘要的兜底。3. 模板实战列表页摘要卡片与“”的正确姿势3.1 一份可以直接用的列表模板弄清楚优先级之后模板里的用法反而简单了。一个标准的列表页卡片长这样{{ range .Pages }} article classpost-card h2 classpost-card__title a href{{ .RelPermalink }}{{ .Title }}/a /h2 {{ if .Summary }} div classpost-card__summary {{ .Summary }} /div {{ end }} {{ if .Truncated }} a classpost-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.htmlarticle classpost-card h2 classpost-card__title a href{{ .RelPermalink }}{{ .Title }}/a /h2 div classpost-card__summary {{ .Summary }} /div {{ if .Truncated }} a classpost-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返回的是安全 HTMLHugo 不会帮你重新清洗标签页面输出时这个p标签就会原样出现。如果摘要卡片外层本身已经包裹了div classpost-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 classpost-card__summary{{ .Summary }}/div {{ end }}120 这个阈值可以根据你的内容风格调整目的是保证过短的文章不会在列表页裸奔。空摘要的情况也要考虑。用!--more--且在正文前没有内容时.Summary就是空字符串模板里如果直接输出会留下空白卡片。所以在输出摘要前我习惯加一个判断{{ if .Summary }} div classpost-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 namedescription 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 和自动截断两种模式有意义。如果你也想给站点做一次体验升级不妨先从列表页的摘要开始这个投入产出比往往比换主题、改配色来得更直接。