WordPress REST API分页异常：仅返回5篇文章但X-WP-Total显示344篇

问题概述 #

X-WP-Total响应头显示站点共有344篇已发布文章，但无论调整per_page、page或offset等分页参数，REST API始终仅返回固定5篇文章，无法正常分页遍历全部内容。

无效API调用示例 #

• 设置per_page=100仍仅返回5篇：

  curl "https://example.com/wp-json/wp/v2/posts?per_page=100&status=publish"
  

• 使用偏移分页offset=100仍返回相同5篇：

  curl "https://example.com/wp-json/wp/v2/posts?per_page=50&offset=100&status=publish"
  

• 使用页码分页page=2仍返回相同5篇：

  curl "https://example.com/wp-json/wp/v2/posts?per_page=50&page=2&status=publish"
  

响应头与实际数据差异 #

• 响应头X-WP-Total: 344（正确声明总已发布文章数）
• 实际JSON响应：固定返回5篇文章，所有分页参数变更后返回内容无变化

已完成排查 #

• 停用全部插件，问题依旧存在
• 测试过per_page值为10、50、100等不同数值
• 验证了偏移分页（offset）和页码分页（page）两种方式
• 尝试调整orderby参数为id、date，无改善
• WordPress后台确认实际存在344+篇已发布文章

可能的解决方向 #

1. 检查主题自定义代码
   查看当前主题的functions.php文件，是否存在修改REST API查询的代码，比如通过rest_post_query过滤钩子强制设置了posts_per_page=5：

   add_filter( 'rest_post_query', function( $args ) {
       $args['posts_per_page'] = 5;
       return $args;
   } );
   

   若有这类代码，删除或修改为动态读取参数值即可。

2. 验证全局posts_per_page设置
   登录WordPress后台，进入「设置-阅读」，检查「博客页面至多显示」的数值是否被设为5。部分主题或自定义代码可能强制将该值同步到API查询中。

3. 排查数据库查询异常
   开启WordPress调试模式，查看REST API执行的SQL查询语句，确认LIMIT子句是否被强制设为5。在wp-config.php中添加：

   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   

   调用API后查看wp-content/debug.log中的SQL日志，定位查询条件异常点。

4. 检查REST路由自定义修改
   确认是否有自定义代码通过register_rest_route修改了默认文章路由的查询逻辑，导致返回数量被限制。可尝试移除自定义路由注册代码测试。

内容的提问来源于stack exchange，提问作者User