Hugo Pages.Next / Pages.Prev 方法解析：页面排序层级与前后页导航的实现机制

本篇技术指南围绕 Hugo 官方文档中 Pages.Next / Pages.Prev 方法条目展开，讲清 Hugo 如何依据 weight、date、linkTitle、path 四级排序层级确定一个页面的"上一页"与"下一页"，并结合 hugolib/site.go 与 hugolib/page__position.go 的源码实现，说明该机制在站点构建期的底层工作过程，帮助你在模板中正确、可控地输出前后导航链接。

一、确定前后页的排序层级

Hugo 在判定某个页面的 next（下一页）与 previous（上一页）时，会先对页面集合按以下层级进行排序（见官方文档 docs/content/en/_common/methods/pages/next-and-prev.md）：

字段	优先级	排序方向
weight	1	降序
date	2	降序
linkTitle	3	降序
path	4	降序

四个字段全部为降序，即"权重越大越靠前、日期越新越靠前、标题与路径越靠后字典序越靠前"。这意味着：

• 只要页面设置了 weight，排序就由它主导；
• 只有 weight 相同或缺失时，才比较 date，以此类推，最后以 path 兜底，保证排序结果确定、可复现。

文档同时给出了一个关键警告：用于判定前后页的已排序页面集合，与其他页面集合相互独立，这可能带来不符合直觉的行为。下面的示例正是为此设计的。

二、典型案例：带 weight 的 sections 页面

文档给出的内容结构如下（三个兄弟页面分别设置递增的 weight）：

content/
├── pages/
│   ├── _index.md
│   ├── page-1.md   <-- front matter: weight = 10
│   ├── page-2.md   <-- front matter: weight = 20
│   └── page-3.md   <-- front matter: weight = 30
└── _index.md

配合两个模板。节列表模板 [layouts/section.html] 按 weight 渲染条目：

{{ range .Pages.ByWeight }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

页面模板 [layouts/page.html] 使用集合上的 Prev / Next 输出导航链接：

{{ $pages := .CurrentSection.Pages.ByWeight }}

{{ with $pages.Prev . }}
  <a href="{{ .RelPermalink }}">Previous</a>
{{ end }}

{{ with $pages.Next . }}
  <a href="{{ .RelPermalink }}">Next</a>
{{ end }}

访问 page-2 时的结果是：

• Prev 方法指向 page-3；
• Next 方法指向 page-1。

为什么方向是"反的"？

按排序层级，ByWeight 后集合顺序为 page-3 (30) → page-2 (20) → page-1 (10)（降序）。Next / Prev 是相对该集合的物理位置定义的：Next 指向集合中的"前一个元素"（索引 i-1），Prev 指向"后一个元素"（索引 i+1）。对位于中间的 page-2 而言，前一个元素是 weight 更大的 page-3，后一个是 page-1，因此语义上出现了"weight 更大却出现在 Prev 侧"的效果。这正是文档所说的"集合相互独立，可能导致意外行为"的具体体现——你在模板中定义集合时用的排序方式，直接决定了导航的方向语义。

ByWeight 方法本身的行为可在官方文档 docs/content/en/methods/pages/ByWeight.md 中进一步查阅，其中也演示了用 .Reverse 翻转排序顺序的写法。

三、反转方向语义：链式调用 Reverse

如果希望"下一页"指向集合中物理位置靠后的页面（即翻转 next/previous 的方向），只需在集合定义后链式调用 Reverse 方法：

{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }}

{{ with $pages.Prev . }}
  <a href="{{ .RelPermalink }}">Previous</a>
{{ end }}

{{ with $pages.Next . }}
  <a href="{{ .RelPermalink }}">Next</a>
{{ end }}

反转后集合顺序变为 page-1 (10) → page-2 (20) → page-3 (30)，此时访问 page-2，Next 指向 page-3、Prev 指向 page-1，与多数用户对"上一页/下一页"的直觉一致。

实操要点小结：

1. 导航方向不由页面本身决定，而由你传给 Prev/Next 的那个集合的排序决定；
2. 同一页面在不同模板中使用不同集合（如 ByWeight 与 ByWeight.Reverse），会得到方向相反的结果，但都"合法"；
3. 需要全局默认行为时，页面方法 .Next / .Prev 与集合方法 .Pages.Next . / .Pages.Prev . 的语义对应关系，见下一节的源码说明。

四、底层实现：构建期惰性生成的 nextPrev 指针

从源码结构看，Hugo 的页面级 p.Next() / p.Prev() 并不在模板执行时动态查找，而是在站点初始化阶段一次性为所有 RegularPages 预计算好指针，且采用惰性求值（首次调用才触发）：

• hugolib/site.go 中，s.init.prevNext 注册了一段初始化逻辑：取出 s.RegularPages()，若站点配置了 page.NextPrevSortOrder == "asc" 则先 Reverse()，然后遍历集合，将每个页面索引 i 的前一个元素赋给 nextPage、后一个元素赋给 prevPage（越界则为 nil）。
• hugolib/page__position.go 定义了 nextPrev 结构体（含 prevPage / nextPage 两个指针及惰性初始化函数），并派生出 pagePosition（对外暴露 Next() / Prev()）与 pagePositionInSection（对外暴露 NextInSection() / PrevInSection()）两种位置封装。
• 同一初始化文件中，hugolib/site.go 还实现了 prevNextInSection：按节（Section/Home）分组取 section.RegularPages()，支持 page.NextPrevInSectionSortOrder == "asc" 时反转，再逐节写入指针——这是 NextInSection / PrevInSection 方法的数据来源。

这种"初始化时写指针、模板里 O(1) 读取"的设计，也解释了为何模板中反复调用 Prev/Next 开销极小。

仓库测试 hugolib/pages_test.go 中的 TestPagesPrevNext 用例进一步验证了两种访问路径的一致性：对 100 个带随机 weight 的页面，断言集合级 pages.Next(p) 与页面级 p.Next()、pages.Prev(p) 与 p.Prev() 的结果完全相等，说明集合方法与页面方法遵循同一套排序与方向约定。

五、适用范围与注意事项

• 本文的排序层级、模板写法与 Reverse 用法均来自当前仓库的官方文档条目 docs/content/en/_common/methods/pages/next-and-prev.md，以仓库实际内容为准；
• 集合方法 .Pages.Prev . / .Pages.Next . 中的第二个参数"当前页"用于在集合内定位自身，定位失败（当前页不在集合内）时按 Hugo 的取值惯例返回零值，模板中可用 with 兜底（示例模板即如此处理）；
• 若页面没有 weight，排序退化为按 date 比较；因此对静态"步骤页/章节页"这类无日期内容，显式写 weight 是获得稳定导航顺序的最可靠做法；
• 涉及全局默认方向调整时，可关注站点配置中的 page.NextPrevSortOrder 与 page.NextPrevInSectionSortOrder（源码中按 "asc" 分支处理），适用于 p.Next() / p.Prev() 这类不经过自定义集合的场景。