WordPress REST API 401/403 怎么排查？先分清接口、鉴权和权限
WordPress REST API 401/403，不一定表示接口被禁用，也不一定是安全插件误杀。更常见的情况是：你访问了一个需要登录的端点，却没有带上正确的认证信息；或者已经登录，但当前账号没有执行这个动作的权限。
排查这类问题，最容易浪费时间的做法是看到 401 或 403 就关防火墙、改固定链接、停用插件。我的习惯是先确认请求有没有到达 WordPress、路由是否存在、目标端点是否允许匿名访问、认证有没有被识别、当前用户是否具备权限。下面这套顺序既适合插件调用失败，也适合 Gutenberg、第三方程序和自动化接口异常。
先看结论：401、403、404 和 5xx 不是一类问题
| 状态或现象 | 通常表示什么 | 第一步检查 |
|---|---|---|
| 200，返回 JSON | 路由存在，请求成功 | 继续核对返回字段是否符合预期 |
| 401 Unauthorized | 当前请求没有被识别为已登录用户，或缺少认证 | Cookie、REST nonce、Application Password 和 Authorization 头 |
| 403 Forbidden | 请求可能已经通过登录识别，但当前用户无权限；也可能被 WAF 直接拦截 | 先分辨响应是 WordPress JSON 还是服务器 HTML |
| 404 / rest_no_route | 路由、命名空间或请求方法不匹配 | API 根、目标路由、插件是否注册该端点 |
| 404 HTML 页面 | 请求可能没有进入 WordPress REST 路由 | 固定链接、Nginx/Apache 重写和真实请求 URL |
| 500、502、503 | PHP、插件、主题、上游服务或服务器异常 | 错误日志、插件冲突和主机状态 |
WordPress 核心的 rest_authorization_required_code() 会根据登录状态返回不同授权错误：未登录时通常是 401，已经登录但不满足权限时通常是 403。因此，401 和 403 的差别本身就是一条排查线索，但还要结合响应正文判断，不能只看浏览器标题栏里的数字。
先确认 WordPress REST API 到底通不通
先测试 API 根，不要一上来就测试需要登录的写入接口。把域名替换成目标网站：
curl -i https://example.com/wp-json/正常情况下会返回 200，响应类型包含 application/json，正文里能看到站点信息、命名空间和路由。这个结果只能证明 REST API 根可访问，不代表所有端点都允许匿名读取，更不代表写入权限正常。
再测试一个公开文章端点，并用 _fields 减少返回内容：
curl -i "https://example.com/wp-json/wp/v2/posts?per_page=1&_fields=id,slug,status"如果 API 根和公开文章端点都是 200，而某个后台或写入端点返回 401，问题重点通常已经从“REST API 是否关闭”转到了“这个端点需要怎样认证”。WordPress 官方也不建议简单禁用整个 REST API，因为区块编辑器和不少后台功能依赖它。
如果 /wp-json/ 本身返回普通 404，可以再试：
curl -i "https://example.com/?rest_route=/"第二种形式正常、第一种不正常时，优先检查固定链接和服务器重写。本站的 WordPress 固定链接 404 排查里有更完整的 Nginx、Apache 和重写规则检查顺序。
一次本站只读实测：同一个接口为什么会从 401 变成 200
为了避免只讲概念，我在本站当前 WordPress 7.1、PHP 8.4.10 环境做了一组只读测试，没有创建、修改或删除内容。2026 年 8 月 22 日的结果如下：
| 测试请求 | 状态 | 说明 |
|---|---|---|
/wp-json/ | 200 | API 根和路由发现正常 |
/wp-json/wp/v2/posts?per_page=1 | 200 | 公开文章端点允许匿名读取 |
/wp-json/wp/v2/users/me | 401 | 匿名请求没有当前用户，这是预期结果 |
post type + context=view | 200 | 公开上下文允许读取 |
post type + context=edit，匿名 | 401 | 错误码为 rest_forbidden_context |
同一 context=edit，管理员上下文 | 200 | 路由本身正常，差别在认证与权限上下文 |
| 不存在的测试路由 | 404 | 错误码为 rest_no_route |
这组结果说明，不能拿一个受保护端点的 401 推断整个 REST API 已损坏。排查时要准备一个公开请求和一个受保护请求作对照，才能知道故障发生在路由层、认证层还是权限层。
WordPress REST API 401 怎么排查
1. 先确认目标端点是否本来就需要登录
公开文章、页面和部分分类法通常可以匿名读取；用户当前身份、后台设置、私密内容、编辑上下文和写入操作通常需要认证。把公开端点返回 200、受保护端点返回 401 视为正常权限边界，而不是故障。
2. 同站后台请求检查 Cookie 与 REST nonce
插件或主题在已登录后台发起请求时，通常使用登录 Cookie 配合 REST nonce。只有 Cookie 没有 nonce，WordPress 可能把请求按未登录用户处理；nonce 过期、缓存了旧 nonce、请求跨域或代理丢失请求头，也会造成 401。
- 确认请求发送到当前站点的正确 REST 根，而不是旧域名或测试站。
- 确认请求带有当前页面生成的
X-WP-Nonce，不要把 nonce 写死在脚本里。 - 排除页面缓存、CDN 或反向代理缓存了登录态相关响应。
- 检查浏览器开发者工具中的请求 URL、状态码和 JSON 错误码。
3. 外部程序优先使用 Application Password
外部脚本、自动化平台或客户端不能直接复用后台 Cookie 与 nonce。WordPress 官方文档建议通过 HTTPS 使用 Application Password，并把账号名和应用密码作为 Basic Authentication 凭据。不要在脚本中保存后台正常登录密码，也不要把凭据写进 URL、日志或公开截图。
curl --user "USERNAME:APPLICATION_PASSWORD"
"https://example.com/wp-json/wp/v2/users/me"这里的示例只说明请求结构。真实应用密码应放在安全的环境变量或密钥管理工具中，不要直接复制进公开命令历史。
4. 检查 Authorization 头有没有到达 PHP
客户端确定发送了认证头，但 WordPress 仍然识别为匿名用户时，要检查 Web 服务器、反向代理和 PHP-FPM 是否保留 Authorization。WordPress REST API FAQ 分别给出了 Apache 与 Nginx 的处理方向。这里不要直接复制一段服务器配置覆盖线上文件，先在测试环境确认当前配置、请求头和 PHP 接收结果。
WordPress REST API 403 怎么排查
403 至少有两种完全不同的来源：WordPress 已识别用户但权限不足，或者请求在到达 WordPress 之前就被主机防火墙、CDN、WAF 或安全插件拦截。先看响应格式：
| 响应特征 | 更可能的来源 | 下一步 |
|---|---|---|
JSON，包含 code、message、data.status | WordPress REST 权限检查 | 核对当前用户角色、能力和端点 permission callback |
| HTML 拒绝页面，带主机或安全服务样式 | CDN、WAF、主机防火墙 | 对照安全日志、规则 ID、请求方法和来源 IP |
| JSON 但错误码来自安全插件 | WordPress 安全插件 | 查看插件日志和 REST 限制设置 |
| 只对 POST、PUT、DELETE 拒绝 | 权限、nonce、请求方法或 WAF 规则 | 用同一路由的 GET/OPTIONS 作对照 |
如果只是某个编辑动作失败，先确认账号是否拥有编辑目标内容的能力。管理员请求成功、编辑者请求失败，往往是权限设计在生效。不要为了让一个接口“变绿”就把所有请求都放行，也不要给普通账号临时提升到管理员后忘记恢复。
404、固定链接和安全插件该什么时候查
只有 API 根或目标路由不存在时，才把重点转到固定链接、重写和插件注册。返回 JSON 的 rest_no_route 通常说明请求已经进入 REST 服务器，只是路径、命名空间、版本、方法或插件路由不匹配；返回主题 404 页面则更像请求没有正确进入 REST 路由。
- 从 API 根确认目标命名空间是否存在。
- 核对插件文档中的路由版本、HTTP 方法和参数名。
- 确认注册路由的插件当前已启用，且没有 PHP 致命错误中断加载。
- 比较
/wp-json/与?rest_route=/的结果。 - 最后才在可回滚条件下检查重写规则、安全插件和 WAF。
如果 REST 请求同时伴随 500 或空白响应，可以结合 WordPress 500 错误与插件冲突排查检查 PHP 日志。安全排查里常有人把 REST API 和 XML-RPC 混在一起；两者不是同一个入口，是否限制也不能互相替代，具体区别可参考 WordPress XML-RPC 要不要禁用。
一套不容易误判的排查顺序
- 保留原始证据：记录完整 URL、HTTP 方法、状态码、Content-Type 和响应正文，先隐藏凭据、Cookie、nonce 与客户信息。
- 测试 API 根：确认 REST 服务和路由发现是否正常。
- 测试公开端点：确认匿名读取链路是否正常。
- 复现目标端点：核对命名空间、方法、参数和上下文。
- 补齐正确认证：同站请求检查 Cookie + nonce，外部程序检查 Application Password 和 Authorization 头。
- 检查权限：确认当前账号对目标对象和动作具备能力。
- 定位拦截层：根据 JSON 或 HTML 响应判断 WordPress、安全插件、WAF、CDN 或主机。
- 最后再改配置：任何停用插件、修改重写或放宽规则都先备份，并在测试环境验证。
这套顺序的重点不是把所有 401/403 都消掉，而是判断当前响应是否符合端点设计。匿名访问 /users/me 返回 401 是正常的；管理员带正确认证仍无法读取必要端点，才是需要继续处理的问题。
常见误区
- 看到 401 就重置固定链接：401 首先属于认证问题，固定链接更常对应 404 或路由不可达。
- 看到 403 就停用所有安全功能：先确认 403 来自 WordPress 还是外围 WAF，并找到具体规则。
- 后台已登录就认为 REST 请求自动登录：同站 Cookie 认证仍需要 REST nonce，跨站外部程序不能复用这套逻辑。
- 用正常后台密码做远程 Basic Auth：外部集成应使用用途独立、可撤销的 Application Password。
- 只看状态码，不看错误码和响应类型：同一个数字可能来自不同层，处理方法完全不同。
总结
排查 WordPress REST API 401/403，先把问题拆成五层：服务可达、路由存在、认证被识别、用户有权限、外围没有拦截。先用 API 根和公开端点建立基线，再复现受保护端点；这样可以避免把正常的权限边界误判成接口故障。
真正需要修改配置时，也应基于已经定位到的层级做最小调整：缺 nonce 就修请求，Authorization 头丢失就查代理链路，能力不足就修权限设计，WAF 命中就处理具体规则。不要用“彻底开放 REST API”来掩盖一个本来可以精确修复的问题。
参考资料：Developer.WordPress.org《REST API Handbook》、《Authentication》、《Frequently Asked Questions》、《Discovery》、《rest_authorization_required_code()》
