一、什么是 WPGraphQL
WPGraphQL 是开源免费 WordPress 插件，为 WP 全站生成标准 GraphQL API，是无头 CMS（Headless WordPress） 行业标准方案，替代传统 WP REST API，专为前后端分离（Next.js/ Astro / Gatsby / SvelteKit）设计。
核心优势
- 按需取数，无冗余：一次请求只拿你声明的字段，解决 REST 接口数据过量（Over-fetch）问题，性能大幅提升（REST 300KB → GraphQL 6KB 同场景）
- 单请求多资源：一篇文章、作者信息、分类、缩略图、站点配置全部一次性获取，不用多次接口轮询
- 强类型自动文档：内置 GraphiQL 可视化调试面板，自动生成字段说明、类型、过滤参数
- 完美兼容 WP 原生逻辑：权限、角色、文章状态、隐私、自定义文章类型 CPT、分类 Taxonomy 全部原生支持
- 高度可扩展：支持 ACF、自定义字段、自定义类型、自定义查询 / 修改（Mutation）
二、安装与基础配置
1. 安装方式
方式 1：后台可视化安装（最简单）
- WP 后台 → 插件 → 添加新插件
- 搜索
WPGraphQL，安装并激活 - 必须开启伪静态链接（固定链接不能为朴素格式），否则接口地址为
/index.php?graphql，规范地址为/graphql
方式 2：WP-CLI
wp plugin install wp-graphql --activate
wp plugin install wp-graphql --activate
方式 3：Composer（项目化推荐）
composer require wpackagist-plugin/wp-graphql
2. 访问调试面板 GraphiQL
激活后后台顶部工具栏出现 GraphiQL IDE 入口，或直接访问： 你的域名/graphql 左侧写查询，右侧实时返回结果，自带自动补全、文档检索功能
三、核心基础查询示例
1. 获取最新文章（基础列表）
query GetRecentPosts {
posts(first: 5, orderby: {field: DATE, order: DESC}) {
nodes {
databaseId
title
slug
date
excerpt
featuredImage {
node {
sourceUrl
altText
}
}
author {
node {
name
avatar { url }
}
}
categories {
nodes { name slug }
}
}
}
}
first:5：分页取前 5 条nodes：简化列表结构（替代传统edges/node）- 一次性拿到文章、缩略图、作者、分类全套数据
2. 根据 ID / 别名查询单篇文章
# 通过数据库ID查询
query GetPostById {
post(id: 12, idType: DATABASE_ID) {
title
content
}
}
# 通过URL别名slug查询
query GetPostBySlug {
post(id: "hello-world", idType: SLUG) {
title
}
}
3. 页面、自定义文章类型 CPT 查询
注册 CPT 时开启 show_in_graphql => true 即可直接查询：
query GetCustomPosts {
books(first:10) { # books 为自定义文章类型名
nodes {
title
databaseId
}
}
}
4. 用户、分类、标签查询
# 获取分类列表
query GetCategories {
categories {
nodes { name slug count }
}
}
# 获取作者用户（公开数据，邮箱等敏感信息需管理员权限）
query GetAuthors {
users {
nodes { name avatar {url} }
}
}
四、Mutations：修改数据（增删改）
GraphQL 中 query 只读，mutation 用于创建 / 更新 / 删除内容，需要登录授权：
mutation CreatePost {
createPost(input: {
title: "GraphQL 测试文章",
content: "测试内容",
status: PUBLISH
}) {
post {
id title
}
}
}
支持更新文章、创建用户、上传媒体、修改分类等完整后台操作。
五、常用配套扩展插件
- WPGraphQL for ACF 最常用扩展，让 Advanced Custom Fields 自定义字段出现在 GraphQL Schema，支持图片、 repeater、关系字段等
- WPGraphQL Smart Cache 缓存查询结果，大幅降低数据库压力，生产环境必备
- WPGraphQL JWT Authentication JWT 令牌登录认证，用于纯前端分离项目（无 WordPress 登录 Cookie）
- WPGraphQL Blocks 读取古腾堡区块（Gutenberg）原始数据，用于前端重构页面组件
六、前端请求示例（Fetch / JavaScript）
const fetchWpGraphql = async () => {
const res = await fetch("https://你的域名/graphql", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
query: `
query GetPosts {
posts(first:3) { nodes { title slug } }
}
`
})
});
const data = await res.json();
console.log(data.data.posts.nodes);
};
前端框架搭配：Apollo Client / Relay /urql 可做缓存、自动刷新。
七、安全与权限机制
- 严格继承 WP 原生权限
- 游客只能读取已发布公开文章、公开作者
- 用户邮箱、草稿、私密文章、后台设置仅对应权限角色可见
- 认证方式
- Cookie 认证：登录 WP 后台后 GraphiQL 自动授权
- JWT Token：无后台登录的纯前端项目
- 防护手段
- 限制查询复杂度，防止恶意超大查询拖垮数据库
- 接口可加 IP 白名单、API 密钥拦截公开访问
八、WPGraphQL vs WP REST API
| 对比项 | WPGraphQL | WP REST API |
|---|---|---|
| 数据获取 | 按需指定字段，无冗余 | 固定返回大量字段，多请求拼接数据 |
| 请求次数 | 一次请求拿多资源 | 文章、作者、分类需多个接口 |
| 类型提示 | 强类型，自动文档 | 无类型，纯 JSON，易出错 |
| 分页过滤 | 统一内置参数 | 各接口参数不统一 |
| 适用场景 | 无头 CMS、Next.js/Gatsby | WP 主题原生 AJAX、简单小程序 |
九、典型应用场景
- 无头 WordPress：WP 做内容后台，Next.js/Astro 做高性能静态前端网站、博客
- 小程序 / APP 后端：统一一套 API 给多端客户端
- 多站点统一内容聚合：单接口拉取全部文章、页面、自定义内容
- 后台自定义仪表盘：PHP 内部执行 GraphQL 查询渲染自定义后台组件