本文介绍在 timber 框架中为 wordpress 单篇文章页添加「循环式前后导航」：当用户到达最新（或最旧）文章时，点击“next”自动跳转至最旧文章（或反之），避免按钮消失，提升浏览连续性。
在默认的 Timber + WordPress 实现中，post.prev 和 post.next 仅在存在相邻文章时返回对象，否则为 null —— 这导致首/末篇文章的对应导航按钮直接消失。要实现「首尾循环」效果，关键在于主动兜底补全缺失的导航目标：当常规相邻文章不存在时，手动查询并注入首篇或末篇作为 fallback。
✅ 推荐实现方案（PHP 层兜底）
在您的 PHP 上下文构建文件（如 single.php 或 index.php）中，替换原有逻辑为以下健壮写法：
$post = new TimberPost();
$context['page'] = $post;
// 获取下一篇文章：优先用 post.next，缺失则取最旧文章（ASC 排序第一篇）
$next_posts = Timber::get_posts([
'posts_per_page' => 1,
'post_status' => 'publish',
'order' => 'ASC',
'orderby' => 'date'
]);
$context['next'] = $post->next ?: (!empty($next_posts) ? $next_posts[0] : $post);
// 获取上一篇文章：优先用 post.prev，缺失则取最新文章（DESC 排序第一篇）
$prev_posts = Timber::get_posts([
'posts_per_page' => 1,
'post_status' => 'publish',
'order' => 'DESC',
'orderby' => 'date'
]);
$context['prev'] = $post->prev ?: (!empty($prev_posts) ? $prev_posts[0] : $post);
⚠️ 注意事项：显式添加 'post_status' => 'publish' 避免草稿干扰；使用 !empty($posts) 判断防止空数组访问报错（比直接 [0] 更安全）；若全站仅有一篇文章，$next 和 $prev 将回退到当前文章本身，避免链接失效。
✅ Twig 模板层简化渲染
此时模板无需条件判断，可直接输出：
<div class="post-prev">
<a href="%7B%7B%20prev.link%20%7D%7D" title="上一篇：{{ prev.title }}">← Previous</a>
</div>
<div class="post-next">
<a href="%7B%7B%20next.link%20%7D%7D" title="下一篇：{{ next.title }}">Next →</a>
</div>
? 进阶建议
- 性能优化：若站点文章量极大（>1000 篇），频繁调用 Timber::get_posts() 可能影响性能。可考虑缓存首/末文章 ID（如使用 wp_cache_set/get），或在主题激活时预存至选项表。
- 自定义排序：如需按标题、自定义字段等排序循环，只需同步修改两处 orderby 参数（保持 next 与 prev 查询方向相反）。
- 无障碍增强：为 标签添加 aria-label 或 title 属性（如示例所示），提升可访问性。
通过该方案，用户可在任意文章页无缝循环浏览全部内容，既保持 UI 一致性，又强化内容发现体验 —— 是数字出版、作品集、博客归档等场景的理想实践。
