Pages

ByExpiryDate

返回给定页面集合按过期日期升序排序后的结果。

签名
PAGES.ByExpiryDate
返回类型
page.Pages

这一页解决什么问题

把页面集合按过期日期(expiryDate)升序重排:最早过期的在前。用来做「即将下线的活动」「限时内容」这类列表。

排序取值由项目配置决定,默认取前置元数据里的 expiryDate。与 date/lastmod/publishDate 不同,expiryDate 没有回落:页面没写它,.ExpiryDate 就是零值 0001-01-01,会排在最前面(实测)。

什么时候用,什么时候别用

该用:

  • 列出有时效的内容,并让快到期的排前面;
  • 配合 where 筛出「尚未过期」的内容(见下面的完整示例)。

别用:

用法

按过期日期排序时,取值由项目配置决定,默认使用前置元数据中的 expiryDate 字段。

go-html-template
{{ range .Pages.ByExpiryDate }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

要改为降序排列:

go-html-template
{{ range .Pages.ByExpiryDate.Reverse }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

完整示例:升序列表 + 只看未过期

示例沿用本章首页的示例站点结构(四页都有 expiryDate):

页面 linkTitle expiryDate
post-1.md alpha 2027-01-01
post-2.md bravo 2027-03-01
post-3.md charlie 2028-02-01
post-4.md delta 2028-01-01
layouts/_default/list.htmlgo-html-template
按过期升序:{{ range .Pages.ByExpiryDate }}{{ .LinkTitle }}={{ .ExpiryDate.Format "2006-01-02" }} {{ end }}
尚未过期:{{ range where .Pages "ExpiryDate" "gt" now }}{{ .LinkTitle }} {{ end }}

Hugo 渲染为(构建日期为 2026-10-03):

html
按过期升序:alpha=2027-01-01 bravo=2027-03-01 delta=2028-01-01 charlie=2028-02-01 
尚未过期:alpha bravo charlie delta 

你应当看到什么:升序按 expiryDate 从早到晚(alpha 2027-01 → bravo 2027-03 → delta 2028-01 → charlie 2028-02);where ... "ExpiryDate" "gt" now 筛掉的是构建时已过期的页面,并且保持 .Pages 的原顺序(alpha bravo charlie delta),不会顺带排序。这一行依赖构建时刻:2028-02 之后 charlie 会自己从名单里消失。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'en-US'、timeZone = 'UTC'),Windows。

情况 结果 是否报错
四页都有 expiryDate 按 expiryDate 升序 否
页面没有 expiryDate .ExpiryDate 为零值 0001-01-01,排在最前(不会回落到 date) 否
页面另有 date、但没有 expiryDate 仍然按零值排序,落在 0001 一组 否
两个页面过期日期相同 组内顺序由内部实现决定,上游未说明 否
空集合 空集合:range 无输出,len 为 0 否
页面的 expiryDate 早于构建日期 该页在默认构建中不参与渲染(不会出现在任何集合里),需要 --buildExpired 才包含 否
返回类型 page.Pages 否

常见坑

类别 症状 真因 怎么修
没报错但结果不对 一批页面排在最前,日期显示 0001-01-01 这些页面没写 expiryDate(该字段不回落) 补 expiryDate,或在模板里跳过零值
没报错但结果不对 明明写了页面却完全不出现 页面的 expiryDate 已过,Hugo 默认不构建过期页面 检查 hugo list expired;确需构建时加 --buildExpired
没报错但结果不对 列表里出现已经过期的内容 排序不做过滤 用 where ... "ExpiryDate" "gt" now 过滤(见完整示例)
没报错但结果不对 降序列表把「无过期日期」的页面排到了最后 零值在升序里最前,反转后就在最后 先剔除零值再排序更直观

更多排查入口见故障排查。