WordPress 本地环境 REST API 404 问题排查记录

发表于 分类于 ， ，
记录了在本地WordPress环境中REST API返回404错误的问题排查过程，分析了问题根源（重写规则失效），并提供了简单有效的解决方案（保存固定链接设置），同时解释了背后的原理。

一、问题背景

在本地 WordPress 开发环境（localhost:2234）中进行页面编辑操作时，浏览器控制台出现如下报错：

1
POST http://localhost:2234/wp-json/wp/v2/pages/5?_locale=user 404 (Not Found)

该报错来源于 WordPress 后台编辑页面（Gutenberg 编辑器）在保存页面内容时，通过 REST API 向 /wp-json/wp/v2/pages/{id} 发送 POST 请求，但服务器返回了 404。

直观表现为：

  • 页面无法正常保存或更新
  • 后台无明显 PHP 报错
  • 前端页面访问可能正常

二、问题初步分析

WordPress 的 REST API 强依赖于 重写规则（Rewrite Rules）。/wp-json/ 本质上并不是一个真实存在的目录，而是通过固定链接规则映射到 WordPress 内部路由。

出现 REST API 404，通常说明：

  • 固定链接重写规则未正确生成或失效
  • Web Server（Apache / Nginx）未正确加载最新 rewrite 规则
  • 本地环境端口、虚拟主机或伪静态配置异常

但在本次问题中：

  • 站点可正常访问
  • /wp-admin/ 可正常登录
  • 仅 REST API 路径返回 404

说明问题更偏向 WordPress 内部重写规则状态异常。

三、最终解决方案

实际解决方式非常简单：

后台 → 设置 → 固定链接 → 不修改任何内容 → 直接点击「保存更改」

保存完成后：

  • REST API 接口立即恢复正常
  • 页面可以正常保存
  • 控制台 404 报错消失

四、原理说明（为什么“保存一次固定链接”就能修复）

当你点击「保存固定链接」时，WordPress 会执行以下关键操作：

  1. 重新生成 Rewrite Rules
  2. 将最新规则写入数据库（wp_options 表）
  3. 在 Apache 环境下尝试更新 .htaccess
  4. 刷新 REST API 路由映射

在以下场景中，rewrite 规则非常容易“失效”：

  • 本地环境端口发生变化（如 80 → 2234）
  • 从其他环境迁移数据库
  • 手动修改过 siteurl / home
  • 安装 / 卸载过与路由相关的插件（多语言、权限、REST 扩展等）
  • Docker / 本地集成环境（如 Laragon、XAMPP、宝塔）重启异常

而 WordPress 默认并不会自动刷新 rewrite 规则，所以就会出现：

页面看似正常，但 REST API 全部 404

五、如何快速判断是不是“固定链接问题”

当你在 WordPress 中遇到以下情况时，可以第一时间尝试“保存固定链接”：

  • /wp-json/ 返回 404
  • Gutenberg 编辑器无法保存
  • Ajax / admin-ajax.php 正常，但 REST API 不通
  • 新注册的自定义 post type 无法访问
  • 自定义路由突然失效

这是一个成本极低、成功率极高的排查步骤。

六、经验总结

  • REST API 404 ≠ 服务器挂了
  • 本地环境问题，优先从 WordPress 内部配置排查
  • “保存一次固定链接” 是 WordPress 开发中的万能急救手段之一

建议在以下时机主动执行一次：

  • 刚搭建完本地环境
  • 数据库迁移后
  • 修改站点 URL 后
  • 出现无法解释的路由问题时

如果你经常进行 WordPress 本地开发、插件开发或外贸站点部署，这类问题几乎是必踩坑，记录下来可以节省大量排查时间。