本文介绍在 timber 框架中为 wordpress 单篇文章页添加「循环翻页」功能：当用户到达最新（或最旧）文章时，点击“next”仍可跳转至第一篇，“previous”则返回最后一篇，实现无缝闭环导航。
在默认的 Timber + WordPress 配置中，post.next 和 post.prev 仅在存在相邻文章时返回对应对象；一旦到达序列边界（如首篇或末篇），其值为 null，导致分页按钮消失。要实现「首尾循环」效果，关键在于：当原生关联文章为空时，主动查询逻辑上的首篇或末篇作为兜底。
✅ 正确实现方式（PHP 层）
在您的 PHP 上下文构建文件（如 single.php 或 index.php）中，替换原有 $context['page'] 赋值逻辑，改用以下健壮写法：
$post = new TimberPost();
// 获取下一篇文章：若存在则用 post.next，否则取最旧文章（ASC 排序的第一条）
$next_query = Timber::get_posts([
'posts_per_page' => 1,
'post_type' => $post->post_type,
'order' => 'ASC',
'post_status' => 'publish'
]);
$next = $post->next ?: (!empty($next_query) ? $next_query[0] : null);
// 获取上一篇文章：若存在则用 post.prev，否则取最新文章（DESC 排序的第一条）
$prev_query = Timber::get_posts([
'posts_per_page' => 1,
'post_type' => $post->post_type,
'order' => 'DESC',
'post_status' => 'publish'
]);
$prev = $post->prev ?: (!empty($prev_query) ? $prev_query[0] : null);
$context['page'] = $post;
$context['next'] = $next;
$context['prev'] = $prev;? 说明： 显式指定 'post_type' 和 'post_status' 确保与当前文章类型和状态一致（避免跨类型误匹配）； 使用 !empty($query) 判断防止 Timber::get_posts() 返回空数组或 false 时触发 Undefined offset 错误； 若站点仅有一篇文章，$next 和 $prev 将指向自身——这是循环逻辑的合理退化行为。
✅ Twig 模板层（简洁无条件渲染）
无需再做存在性判断，直接输出链接即可：
<div class="post-prev">
<a href="{{ prev.link }}" aria-label="Go to previous post">{{ prev.title }}</a>
</div>
<div class="post-next">
<a href="{{ next.link }}" aria-label="Go to next post">{{ next.title }}</a>
</div>? 提示：添加 aria-label 可提升无障碍访问体验；若需显示标题而非固定文字“Previous/Next”，推荐使用 {{ prev.title }} 增强语义性。
⚠️ 注意事项
- 性能考虑：该方案每次单页请求会额外执行最多两次 WP_Query（当处于首/尾时）。若网站文章量极大（>10k），建议配合对象缓存（如 Redis）或预生成循环映射表优化；
- 排序一致性：确保 PHP 查询中的 orderby 与 Timber 默认 post.next/prev 的排序逻辑一致（默认按 date DESC），否则循环顺序可能出现错位；
- 自定义排序场景：若您已通过 timber_post_next / timber_post_prev 过滤器修改了默认关联逻辑，请同步调整兜底查询的 orderby 参数（例如按 menu_order 或自定义字段）。
通过以上改造，您将获得一个鲁棒、语义清晰且用户体验连贯的循环文章导航系统——无论读者从哪一篇开始浏览，都能无限穿梭于内容宇宙之中。
