本文介绍在 timber + twig 环境下，为 wordpress 单文章页添加「循环导航」功能：当用户浏览至最新文章时，点击“next”可跳转到最旧文章；浏览至最旧文章时，点击“previous”则返回最新文章，形成闭环式阅读体验。
要实现单篇文章页的首尾循环导航（即“最后一片文章 → 点击 Next → 跳转至第一篇”，“第一篇文章 → 点击 Previous → 跳转至最后一篇”），关键在于不依赖默认的 post.prev / post.next 的空值判断逻辑，而是主动兜底获取首/末文章。
默认情况下，Timber 的 post.prev 和 post.next 仅基于当前排序下的相邻文章——若无前/后文，其值为 null 或 false，导致按钮消失。而循环导航要求：无论当前是否为首/尾，prev 和 next 始终有值。
✅ 正确实现方式（PHP 层兜底）
在您的 PHP 上下文构建文件（如 single.php）中，替换原有逻辑，使用 Timber::get_posts() 主动查询首尾文章作为 fallback：
$post = new TimberPost();
$context['page'] = $post;
// 获取下一篇文章：优先用内置 next，否则取最旧文章（ASC 排序取第 1 篇）
$next_posts = Timber::get_posts([
'posts_per_page' => 1,
'post_status' => 'publish',
'order' => 'ASC',
'orderby' => 'date'
]);
$context['next'] = $post->next ?: ($next_posts[0] ?? null);
// 获取上一篇文章：优先用内置 prev，否则取最新文章（DESC 排序取第 1 篇）
$prev_posts = Timber::get_posts([
'posts_per_page' => 1,
'post_status' => 'publish',
'order' => 'DESC',
'orderby' => 'date'
]);
$context['prev'] = $post->prev ?: ($prev_posts[0] ?? null);
⚠️ 注意事项：必须显式指定 'post_status' => 'publish'，避免草稿或私密文章被误选；使用 ?? null 替代直接索引 [0]，防止 Timber::get_posts() 返回空数组时触发 Undefined offset 错误；若站点文章极少（如仅 1 篇），$post->next 和 $post->prev 均为空，此时 next 和 prev 将指向同一篇文章——属合理行为，无需额外拦截。
✅ Twig 模板层（简洁无条件渲染）
在 .twig 模板中，不再需要 {% if %} 判断，直接输出链接即可：
<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>
你还可以增强用户体验，例如为当前文章添加 aria-current="page" 或禁用自身链接，但核心循环逻辑已在 PHP 层稳健保障。
? 总结
循环翻页不是 UI 层的“小技巧”，而是数据逻辑的主动设计。通过放弃对 post.prev/next 的被动依赖，改用可控查询兜底，既保持了 Timber 的简洁性，又赋予了导航真正的闭环能力。适用于作品集、博客归档、教学序列等需线性遍历的场景——让用户永远有路可走。
