本文介绍在 timber 框架中，通过 php 预处理获取首尾文章对象，实现单篇文章页“上一篇→第一篇”“下一篇→最后一篇”的无缝循环导航，避免按钮消失，提升用户体验。
在基于 Timber + Twig 构建的 WordPress 主题中，常规的 post.prev 和 post.next 仅在相邻文章存在时返回对象；一旦到达首篇或末篇，对应属性为 null，导致导航按钮消失。而实际业务中（如作品集、时间线展示或轮播式阅读），常需首尾循环跳转：点击“Next”到末篇后，再点一次应跳回首篇；同理，“Previous”到首篇后应跳至末篇。
✅ 正确实现方式：预加载兜底文章
核心思路是——不依赖 post.prev/next 的有无，而是主动构造“逻辑上的上一篇/下一篇”：
- 若当前文章有真实上一篇，则用它；否则取按时间倒序排列的最后一篇（即最老的文章）；
- 若有真实下一篇，则用它；否则取按时间正序排列的第一篇（即最新文章）。
对应 PHP 逻辑（建议写入 single.php 或自定义模板控制器）：
$post = new Timber\Post();
$context = Timber::get_context();
$context['page'] = $post;
// 获取「逻辑上」的上一篇：优先用 post.prev，缺失则取最老文章（DESC 排序下的最后一个）
$prev_posts = Timber::get_posts([
'post_type' => 'post',
'posts_per_page' => 1,
'order' => 'DESC',
'orderby' => 'date'
]);
$context['prev'] = $post->prev ?: (!empty($prev_posts) ? $prev_posts[0] : null);
// 获取「逻辑上」的下一篇：优先用 post.next，缺失则取最新文章（ASC 排序下的第一个）
$next_posts = Timber::get_posts([
'post_type' => 'post',
'posts_per_page' => 1,
'order' => 'ASC',
'orderby' => 'date'
]);
$context['next'] = $post->next ?: (!empty($next_posts) ? $next_posts[0] : null);⚠️ 注意事项： Timber::get_posts() 在无结果时返回空数组 []，而非 null 或 false，因此用 !empty() 判断更安全； 若站点可能仅有一篇文章，请额外判断 $context['prev'] 和 $context['next'] 是否为 null，避免 Twig 渲染时报错（如加 {{ prev.link|default('#') }}）； 查询参数（如 post_type、post_status）需与主查询保持一致（例如排除 draft），确保循环范围准确。
✅ Twig 模板：简洁无条件渲染
此时 .twig 文件可完全去掉 {% if %} 判断，直接输出链接：
<div class="post-prev">
<a href="{{ prev.link|default('#') }}" aria-label="上一篇：{{ prev.title|e }}">← Previous</a>
</div>
<div class="post-next">
<a href="{{ next.link|default('#') }}" aria-label="下一篇：{{ next.title|e }}">Next →</a>
</div>使用 |default('#') 可防止单篇文章场景下链接为空导致 HTML 错误；搭配 aria-label 提升无障碍访问体验。
✅ 总结
循环导航不是前端“补丁”，而是数据层的逻辑增强。通过在 PHP 层主动兜底获取首/末文章，并交由 Twig 统一渲染，既保证了代码健壮性，又让模板极度简洁。该方案兼容 Timber 2.x / 3.x，无需修改主题主循环逻辑，推荐作为单文章页导航的标准实践。
