完整的 WordPress REST API 指南 2026

Learn endpoints, authentication, CRUD operations, and how to build headless CMS with WordPress

什么是 WordPress REST API

WordPress REST API 是一个桥梁，允许外部应用程序（如移动应用、React 前端或其他服务）与您的 WordPress 网站交互，而无需接触管理仪表板或通过传统 HTML 表单写入数据。REST API 不依赖于 HTML 页面，而是使用 JSON（JavaScript 对象表示法）—— 一种在服务器和客户端之间交换数据的轻量级标准格式。

REST API 在 2017 年 1 月随 WordPress 4.7 版本引入，从那时起就成为 WordPress 核心的一部分，持续接收更新和改进。使用 REST API 使您能够构建无头 CMS —— 将内容管理系统（后端，由管理员使用）与前端呈现（用户在屏幕上看到的内容）分离。这种分离提供了极大的灵活性和强大功能。

在 REST API 出现之前，如果您想让移动应用从 WordPress 读取数据，必须使用 XML-RPC，这既繁琐又缓慢。如今，REST API 允许直接的 HTTP GET 请求（使用 JSON），使构建移动应用、React/Vue 前端或由 WordPress 作为内容后端驱动的 Next.js 网站变得容易得多。REST API 在现代 Web 开发中的简洁性和普遍性使 WordPress 成为无头架构的更有吸引力的选择。

主要 REST API 端点

WordPress REST API 遵循 RESTful 标准约定。所有端点都以 /wp-json/ 为前缀，后跟命名空间和路由。主要的 WordPress 端点位于 /wp-json/wp/v2/，其中 v2 表示 WordPress REST API 的第 2 版。

WordPress 核心端点包括：

• /wp-json/wp/v2/posts — 博客文章
• /wp-json/wp/v2/pages — 静态页面
• /wp-json/wp/v2/categories — 文章分类
• /wp-json/wp/v2/tags — 文章标签
• /wp-json/wp/v2/users — 用户信息
• /wp-json/wp/v2/comments — 评论
• /wp-json/wp/v2/media — 附件和图像
• /wp-json/wp/v2/settings — 网站设置

除了 WordPress 核心，插件还可以注册自己的端点。例如，WooCommerce 为电子商务功能添加了 /wp-json/wc/v3/，例如 /wp-json/wc/v3/products 用于获取产品数据。自定义插件遵循类似的模式，创建与其他命名空间的端点和平共存。

所有端点都支持不同的 HTTP 方法（谓词）：

• GET — 检索数据（大多数公共端点允许此操作而无需身份验证）
• POST — 创建新数据（需要身份验证和适当权限）
• PUT / PATCH — 修改现有数据（需要身份验证和权限）
• DELETE — 删除数据（需要身份验证和权限）

获取文章和页面

从 REST API 检索博客文章是最简单的用例 —— 不需要身份验证，可以从浏览器中运行的 JavaScript 或任何语言的服务器端代码执行。

示例：获取 10 篇最近发布的文章：

GET https://example.com/wp-json/wp/v2/posts?per_page=10&status=publish

响应是一个 JSON 数组，每个文章对象包含：

{
  "id": 123,
  "date": "2026-06-29T10:30:00",
  "title": {
    "rendered": "WordPress REST API Guide"
  },
  "content": {
    "rendered": "<p>...</p>"
  },
  "excerpt": {
    "rendered": "Learn how to use..."
  },
  "featured_media": 456,
  "categories": [1, 2],
  "author": 1,
  "status": "publish"
}

您可以使用查询参数过滤和排序结果：

• ?per_page=20 — 每页返回 20 篇文章（默认为 10）
• ?page=2 — 获取第二页的结果（分页）
• ?search=api — 搜索包含"api"的文章
• ?categories=1,2 — 返回分类 ID 1 和 2 的文章
• ?orderby=date&order=asc — 按日期排序，最旧的在前
• ?_fields=id,title,date — 仅返回特定字段以减少有效负载大小

要通过 ID 获取单篇文章：

GET https://example.com/wp-json/wp/v2/posts/123

单篇文章的响应包含比列表视图更多的详细信息 —— 完整内容、元字段和列表端点中未公开的其他信息。

REST API 身份验证

写入操作（POST、PUT、DELETE）和访问私有/草稿文章需要身份验证以验证用户是否有权限。WordPress 支持多种身份验证方法：

1. 应用程序密码（推荐）

WordPress 5.6+ 提供应用程序密码 —— 用户从 WordPress 管理员 > 用户 > 您的个人资料 > 应用程序密码生成的特殊仅限 API 的凭证。这些比共享您的真实密码更安全，可以单独撤销而不影响您的主要登录。

使用 cURL 的用法示例：

curl -X POST https://example.com/wp-json/wp/v2/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'username:app-password' | base64)" \
  -d '{
    "title": "My New Post",
    "content": "Post content here",
    "status": "publish"
  }'

2. OAuth 2.0（适用于第三方应用）

安装了 OAuth2 插件（如 OAuth2 Server）的 WordPress 允许第三方应用请求访问令牌，而无需暴露用户密码。正在进行工作以向 WordPress 核心添加本机 OAuth2 支持。

3. JWT（JSON Web 令牌）

JWT 插件（如 Simple JWT Authentication）提供基于令牌的身份验证，适用于移动应用和单页应用（SPA）。客户端进行一次身份验证并接收授予有限时间访问权限的令牌。

创建、更新和删除数据

验证后，您可以创建、修改和删除文章和其他内容：

创建新文章：

POST https://example.com/wp-json/wp/v2/posts
Authorization: Basic base64(username:app-password)
Content-Type: application/json

{
  "title": "My First REST API Post",
  "content": "<p>This post was created via REST API</p>",
  "excerpt": "A short excerpt",
  "featured_media": 789,
  "categories": [1, 2],
  "tags": [5, 6],
  "status": "draft"
}

POST 请求中支持的字段：

• title — 文章标题
• content — 正文内容（接受 HTML）
• excerpt — 在文章列表中显示的摘要
• featured_media — 特色图像附件的 ID
• categories, tags — 分类/标签 ID 数组
• status — "draft"、"publish"、"pending"或"private"
• comment_status — "open"或"closed"
• meta — 自定义元字段（如果正确注册）

更新现有文章：

PUT https://example.com/wp-json/wp/v2/posts/123
Authorization: Basic base64(username:app-password)
Content-Type: application/json

{
  "title": "Updated Title",
  "content": "<p>Updated content</p>",
  "status": "publish"
}

更新时，您只需包含要更改的字段 —— 省略的字段保持不变。

删除文章：

DELETE https://example.com/wp-json/wp/v2/posts/123?force=true
Authorization: Basic base64(username:app-password)

force=true 参数表示永久删除文章。不使用它时，文章将移到垃圾桶。

构建自定义端点

除了内置端点，WordPress 允许开发人员创建自定义端点以实现特定于应用的功能：

展示如何注册自定义端点的 PHP 示例：

add_action( 'rest_api_init', function() {
  register_rest_route( 'myapp/v1', '/greet', array(
    'methods'  => 'GET',
    'callback' => 'my_greet_callback',
    'permission_callback' => '__return_true'
  ) );
} );

function my_greet_callback( $request ) {
  $name = $request->get_param( 'name' );
  return new WP_REST_Response( array(
    'greeting' => 'Hello, ' . $name . '!'
  ), 200 );
}

现在您可以调用：

GET https://example.com/wp-json/myapp/v1/greet?name=John

自定义端点适用于：

• 聚合来自多个自定义文章类型的复杂数据
• 接受来自前端的表单提交
• 与支付网关或第三方服务集成
• 实现高级搜索或过滤逻辑

无头 WordPress 架构

无头 CMS 意味着 WordPress 处理内容管理（通过管理员仪表板）但没有主题或前端 —— 这是使用 React、Vue、Next.js 或静态站点生成器等现代框架单独构建的。前端专门通过 REST API 与 WordPress 通信。

无头 WordPress 的优势：

• 灵活性 — 构建任何前端设计，不受主题限制
• 多渠道发布 — 相同的内容同时为网络、移动应用和其他平台提供服务
• 性能 — Next.js 和静态生成器在性能上远超传统 WordPress 主题
• 关注点分离 — 内容团队和前端开发人员可以独立工作

无头 WordPress 架构图：

┌─────────────────────────────┐
│  WordPress Admin Dashboard  │
│  (Content Management)       │
├─────────────────────────────┤
│   WordPress Database        │
│   REST API Endpoints        │
└──────────────────┬──────────┘
                   │
        ┌──────────┼──────────┬──────────┐
        │          │          │          │
     ┌──▼──┐   ┌──▼──┐   ┌──▼──┐   ┌──▼──┐
     │React│   │Next │   │Mobile│   │IOS  │
     │Web  │   │.js  │   │App   │   │App  │
     └─────┘   └─────┘   └──────┘   └─────┘

从 WordPress REST API 获取的 React 组件示例：

// React component
import { useEffect, useState } from 'react';

export default function PostList() {
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    fetch('https://example.com/wp-json/wp/v2/posts')
      .then(res => res.json())
      .then(data => setPosts(data));
  }, []);

  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title.rendered}</h2>
          <p>{post.excerpt.rendered}</p>
        </article>
      ))}
    </div>
  );
}

REST API 安全

REST API 默认对公众开放（仅用于只读访问），因此安全考虑很重要：

1. 禁用不必要的端点

如果您的 WordPress 不为用户或评论数据提供 REST 请求，请考虑禁用这些端点：

// Hide user endpoints from unauthenticated requests
add_filter( 'rest_endpoints', function( $endpoints ) {
  if ( ! is_user_logged_in() ) {
    unset( $endpoints['/wp/v2/users'] );
    unset( $endpoints['/wp/v2/users/(?P<id>[\\d]+)'] );
  }
  return $endpoints;
} );

2. 使用应用程序密码，不使用真实密码

始终为 API 访问使用应用程序密码。您可以立即撤销它们而无需更改您的登录密码，限制泄露时的损害。

3. 实施速率限制

速率限制可防止暴力攻击和 DDoS 滥用：

// Limit to 100 requests per minute per IP
add_filter( 'rest_throttle_check', function() {
  $ip = $_SERVER['REMOTE_ADDR'];
  $key = 'rest_limit_' . $ip;
  $count = get_transient( $key );
  if ( $count >= 100 ) {
    return new WP_Error( 'rest_throttled', 'Too many requests' );
  }
  set_transient( $key, $count + 1, 60 );
} );

4. 始终使用 HTTPS

确保您的 WordPress 托管使用 HTTPS（SSL/TLS）证书。通过未加密的 HTTP 发送应用程序密码容易被拦截。

5. 检查用户权限

在允许写入操作之前验证用户是否具有适当的能力：

register_rest_route( 'myapp/v1', '/admin-only', array(
  'callback'            => 'my_admin_callback',
  'permission_callback' => function() {
    return current_user_can( 'manage_options' );
  }
) );

真实用例

1. 博客的移动应用

原生 iOS 和 Android 应用可以从 WordPress REST API 获取文章并以应用原生格式显示它们。推送通知在发布新文章时提醒用户 —— 在网络浏览器之外创建参与。

2. Next.js 博客配合静态生成

Next.js getStaticProps 在构建时从 WordPress 获取文章，生成静态 HTML。增量静态再生成（ISR）让您在内容更新时按需刷新页面。结果是闪电般快速的页面加载，同时通过 WordPress 管理员保持动态内容管理。

3. 表单提交记录

React 前端上的联系表单可以通过 REST API 向 WordPress 自定义文章类型发送提交。网站管理员直接在 WordPress 管理员仪表板中查看提交，将所有用户交互集中在一起。

// React form submission
async function handleSubmit(e) {
  e.preventDefault();
  const response = await fetch(
    'https://example.com/wp-json/myapp/v1/submissions',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + token
      },
      body: JSON.stringify({
        name: form.name,
        email: form.email,
        message: form.message
      })
    }
  );
  const result = await response.json();
  alert('Thank you for your message!');
}

4. 使用 Jamstack 的多站点发布

拥有多个网站的组织可以使用单个 WordPress 实例作为内容中心。使用 Hugo、Gatsby、11ty 或 Next.js 构建的各个网站通过 REST API 获取数据，可以集中管理内容，同时保持独立的前端架构。