一、基础介绍
1. 什么是 WP REST API
WordPress REST API（官方名称：WP JSON REST API）是 WP 内置接口，通过标准 HTTP 请求（GET/POST/PUT/DELETE），以 JSON 格式读写网站数据，无需登录后台，可用于：
- 前端分离开发（Vue/React/ 小程序 / APP）
- 第三方工具同步文章、用户、媒体
- 自动化发布、采集、数据统计
- 插件 / 外部系统对接 WP
2. 启用条件
- WordPress 4.7+ 原生内置，无需额外插件
- 永久链接不能是「朴素链接」（后台 → 设置 → 固定链接，选任意非纯数字格式）
- 服务器支持 URL 重写（Apache/Nginx 伪静态）
3. 基础地址（路由根节点）
站点根域名 + /wp-json/wp/v2/ 示例：
https://www.mydata-api.com/wp-json/wp/v2/
访问该地址可查看全部可用接口列表。
二、常用核心接口（v2 版本）
1. 文章 Posts
| 请求 | 接口 | 作用 |
|---|---|---|
| GET | /wp-json/wp/v2/posts | 获取文章列表 |
| GET | /wp-json/wp/v2/posts/{id} | 获取单篇文章详情 |
| POST | /wp-json/wp/v2/posts | 新建文章（需权限） |
| PUT | /wp-json/wp/v2/posts/{id} | 修改文章 |
| DELETE | /wp-json/wp/v2/posts/{id} | 删除文章 |
GET 参数筛选示例
# 获取已发布、每页10篇、按发布时间倒序 https://www.mydata-api.com/wp-json/wp/v2/posts?status=publish&per_page=10&orderby=date&order=desc # 分类ID=3的文章 ?categories=3 # 标签ID=5 ?tags=5 # 搜索关键词 ?search=教程
2. 页面 Pages
GET /wp-json/wp/v2/pages GET /wp-json/wp/v2/pages/10
3. 分类 Categories / 标签 Tags
# 分类 /wp-json/wp/v2/categories # 标签 /wp-json/wp/v2/tags
4. 媒体附件 Media（图片 / 文件）
GET /wp-json/wp/v2/media POST /wp-json/wp/v2/media # 上传图片
5. 用户 Users
/wp-json/wp/v2/users /wp-json/wp/v2/users/me # 当前登录用户信息（鉴权后）
6. 自定义文章类型 CPT
假设自定义文章类型 book：
/wp-json/wp/v2/book
三、鉴权方式（读写操作必须授权）
公开 GET 查询文章无需权限；发布、编辑、删除、上传必须身份验证。
方式 1：Application Passwords 应用密码（推荐，WP5.6 + 原生）
- 后台 → 用户 → 个人资料，拉到最下方「应用密码」
- 输入应用名称（如小程序、Python 脚本），生成密码
- 请求时使用 Basic Auth：
- 用户名：WP 登录账号
- 密码：生成的应用密码（不是后台登录密码）
curl 示例新建文章：
curl --user "admin:xxxx xxxx xxxx xxxx" \
-X POST https://www.mydata-api.com/wp-json/wp/v2/posts \
-H "Content-Type: application/json" \
-d '{
"title": "API测试文章",
"content": "正文内容",
"status": "publish"
}'
方式 2：JWT Authentication 插件（适合前后端分离 APP）
安装 WP JWT 插件，登录获取 token，请求头携带：
Authorization: Bearer {token}
方式 3：Cookie 认证（仅同域名前端 JS）
仅限本站前端，跨域无效。
四、跨域 CORS 解决（前端 Vue/React 访问报错）
方案 1：functions.php 添加代码
add_action('rest_api_init', function () {
remove_filter('rest_pre_serve_request', 'rest_send_cors_headers');
}, 15);
add_filter('rest_pre_serve_request', function ($value) {
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
header('Access-Control-Allow-Headers: Access-Control-Allow-Headers, Content-Type, Authorization');
return $value;
});
生产环境不建议 *，替换为你的前端域名更安全。
方案 2：Nginx 配置跨域
location /wp-json/ {
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods GET,POST,OPTIONS,PUT,DELETE;
if ($request_method = OPTIONS) {
return 204;
}
}
五、自定义扩展 REST API
1. 新增自定义接口路由
在主题 functions.php 或自定义插件：
add_action('rest_api_init', function () {
register_rest_route(
'myapi/v1', // 命名空间
'/hello', // 路由地址
[
'methods' => 'GET',
'callback' => 'api_hello_func'
]
);
});
function api_hello_func() {
return rest_ensure_response([
'msg' => '自定义接口成功',
'time' => date('Y-m-d H:i:s')
]);
}
访问地址：/wp-json/myapi/v1/hello
2. 给文章接口增加自定义字段
// 注册自定义字段到API
register_rest_field('post', 'custom_price', [
'get_callback' => function ($post) {
return get_post_meta($post['id'], 'custom_price', true);
}
]);
请求文章接口时会自动返回 custom_price 字段。
六、常见限制与安全优化
- 分页默认最多 100 条 参数 per_page 最大 100，如需更多需过滤修改：
add_filter('rest_post_collection_params', function($params){ $params['per_page']['maximum'] = 200; return $params; }); - 关闭 API（不需要时）
// 完全禁用REST API add_filter('rest_authentication_errors', function ($result) { return new WP_Error('rest_disabled', 'API已关闭', ['status' => 403]); }); // 移除头部link标签里的api地址 remove_action('wp_head', 'rest_output_link_wp_head'); - 安全建议
- 不暴露用户列表：限制 /wp-json/wp/v2/users 访问
- 应用密码定期轮换，不泄露
- 全站 HTTPS，防止鉴权信息劫持
- 限制允许跨域的域名，不要全局 *
- 配合 WAF 限制高频 API 请求防采集、爆破
七、前端 JS 简单调用示例
// 获取文章列表
async function getPosts() {
const res = await fetch('https://www.mydata-api.com/wp-json/wp/v2/posts?per_page=5');
const posts = await res.json();
console.log(posts);
}
// 鉴权发布文章（需跨域+应用密码）
async function createPost() {
const auth = btoa('你的用户名:应用密码');
await fetch('https://www.mydata-api.com/wp-json/wp/v2/posts', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Basic ${auth}`
},
body: JSON.stringify({
title: 'JS创建的文章',
content: 'API内容',
status: 'draft'
})
})
}
八、常用调试工具
- Postman / Apifox：可视化测试所有接口、鉴权
- WP REST API Controller 插件：可视化管理自定义字段、路由
- JSON Formatter：浏览器格式化返回的 JSON 数据