汤不热吧
随着前端技术的飞速发展，传统 WordPress 主题开发模式正在被一种更灵活的架构取代——Headless CMS（无头内容管理系统）。在这种架构中，WordPress 仅作为内容管理后端，前端则使用 Next.js、Gatsby、Vue 等现代框架独立构建。这种方式不仅解耦了前后端，还带来了更好的性能、更强的灵活性和更优的开发体验。本文将从实际工程角度出发，详细讲解如何搭建一个完整的 WordPress Headless CMS 系统。
一、什么是 Headless WordPress？为什么选择它？
传统 WordPress 是一个「全栈」系统——它同时负责内容管理和前端渲染。主题文件中的 PHP 模板决定了页面的最终呈现。而 Headless WordPress 则将这两层完全分离：WordPress 只负责内容的创建、存储和管理，前端则通过 API（REST API 或 GraphQL）获取数据并自行渲染。
传统模式 vs Headless 模式对比
| 维度 | 传统 WordPress | Headless WordPress |
|---|---|---|
| 前端技术 | PHP 模板引擎 | Next.js / React / Vue 等任意框架 |
| 渲染方式 | 服务端渲染 (SSR) | SSR + SSG + ISR 多种选择 |
| 性能 | 依赖插件和缓存优化 | 前端可极致优化，CDN 友好 |
| 内容分发 | 单一网站 | 同一后端服务多端（Web、App、小程序） |
| 开发体验 | PHP + WordPress 生态 | 现代前端工具链，TypeScript 支持 |
| SEO | 原生友好 | 需额外配置，但 SSR/SSG 同样友好 |
选择 Headless WordPress 的核心理由包括：
- 多端内容复用：同一套 WordPress 数据可以同时服务于网站、移动 App、微信小程序，避免内容重复维护。
- 前端自由度：不再受 WordPress 主题机制的束缚，可以使用任何前端框架和组件库。
- 性能潜力：前端框架的静态生成（SSG）和增量静态再生（ISR）能力，配合 CDN 可实现毫秒级响应。
- 安全加固：WordPress 后端可以部署在内网，只通过 API 暴露数据，大幅减少攻击面。
二、WordPress 后端配置：为 Headless 模式做好准备
将 WordPress 用作 Headless CMS，需要做一系列后端配置，确保 API 可用、安全可控、性能达标。
2.1 禁用前端，只保留 API
最简单的方式是在主题的
1 | functions.php |
中拦截所有非 API 请求，将前端访问重定向或返回 404：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 在子主题的 functions.php 中添加
add_action('template_redirect', function() {
if (!defined('REST_REQUEST') && !is_admin() && !wp_doing_ajax()) {
// 方式一：重定向到前端站点
// wp_redirect('https://frontend.example.com' . $_SERVER['REQUEST_URI']);
// exit;
// 方式二：返回 404
status_header(404);
nocache_headers();
include(get_404_template());
exit;
}
});
</php>
更彻底的做法是直接删除
1 | wp-content/themes/ |
下的所有主题，仅保留一个最小的空白主题，只包含
1 | style.css |
和
1 | index.php |
：
2
3
4
5
6
7
8
9
/*
Theme Name: Headless Blank
Description: 最小化主题，仅供 Headless CMS 使用
Version: 1.0
*/
// index.php — 空文件或仅包含一行
<?php // Silence is golden
2.2 安装 WPGraphQL 插件
虽然 WordPress 自带 REST API，但 GraphQL 在 Headless 场景下有显著优势：客户端可以精确声明需要的数据字段，避免过度获取（over-fetching）和获取不足（under-fetching）。
2
3
wp plugin install wpgraphql --activate
wp plugin install wpgraphql-smart-cache --activate # GraphQL 缓存
安装完成后，访问
1 | https://your-wp-site.com/graphql |
即可进入 GraphiQL IDE 进行查询测试。
2.3 自定义 GraphQL 字段
实际项目中，往往需要在 GraphQL Schema 中注册自定义字段。例如为文章添加阅读时间估算：
2
3
4
5
6
7
8
9
10
11
register_graphql_field('Post', 'readingTime', [
'type' => 'String',
'description' => '预估阅读时间（分钟）',
'resolve' => function($post) {
$content = get_the_content(null, false, $post);
$word_count = str_word_count(wp_strip_all_tags($content));
return ceil($word_count / 300) . ' 分钟';
}
]);
});
对于 ACF（Advanced Custom Fields）字段，安装
1 | wp-graphql-acf |
插件即可自动将 ACF 字段注册到 GraphQL Schema 中，无需手动注册。
2.4 配置 CORS 和认证
Headless 架构下前端和后端通常不在同一域名，必须配置 CORS：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
add_filter('graphql_response_headers_to_send', function($headers) {
$headers['Access-Control-Allow-Origin'] = 'https://frontend.example.com';
$headers['Access-Control-Allow-Headers'] = 'Content-Type, Authorization';
$headers['Access-Control-Allow-Methods'] = 'POST, GET, OPTIONS';
return $headers;
});
});
// 处理 OPTIONS 预检请求
add_action('init', function() {
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
header('Access-Control-Allow-Origin: https://frontend.example.com');
header('Access-Control-Allow-Headers: Content-Type, Authorization');
header('Access-Control-Allow-Methods: POST, GET, OPTIONS');
status_header(200);
exit;
}
});
对于需要用户登录的场景（评论、会员内容等），推荐使用 JWT 认证：
在
1 | wp-config.php |
中配置 JWT 密钥：
2
define('JWT_AUTH_CORS_ENABLE', true);
三、Next.js 前端：构建高性能 Headless 站点
Next.js 是目前 Headless WordPress 的首选前端框架，它原生支持 SSR、SSG 和 ISR，与 WordPress 的内容发布模式天然契合。
3.1 项目初始化
2
3
4
cd headless-wp-frontend
npm install graphql graphql-request @tanstack/react-query
3.2 配置 GraphQL 客户端
创建一个统一的 GraphQL 客户端，方便全局复用：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { GraphQLClient } from 'graphql-request';
const WORDPRESS_API_URL = process.env.NEXT_PUBLIC_WORDPRESS_API_URL
|| 'https://wp.example.com/graphql';
export const client = new GraphQLClient(WORDPRESS_API_URL, {
headers: {
'Content-Type': 'application/json',
},
});
// 需要 Authorization 时
export const authedClient = (token: string) =>
new GraphQLClient(WORDPRESS_API_URL, {
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
});
3.3 定义 GraphQL 查询
将查询集中管理，便于维护和复用：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
import { gql } from 'graphql-request';
export const GET_ALL_POSTS = gql`
query GetAllPosts($first: Int = 10, $after: String) {
posts(first: $first, after: $after) {
pageInfo {
hasNextPage
endCursor
}
nodes {
id
slug
title
excerpt
date
readingTime
featuredImage {
node {
sourceUrl(size: MEDIUM_LARGE)
altText
}
}
categories {
nodes {
slug
name
}
}
}
}
}
`;
export const GET_POST_BY_SLUG = gql`
query GetPostBySlug($slug: ID!) {
post(id: $slug, idType: SLUG) {
id
title
content
date
author {
node {
name
avatar {
url
}
}
}
categories {
nodes {
name
slug
}
}
seo {
metaDesc
title
opengraphImage {
sourceUrl
}
}
}
}
`;
export const GET_ALL_CATEGORIES = gql`
query GetAllCategories {
categories {
nodes {
id
slug
name
count
}
}
}
`;
3.4 文章列表页（ISR 模式）
使用 Next.js App Router 的 ISR（增量静态再生），既享受静态页面的速度，又能在 WordPress 发布新文章后自动更新：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
import { client } from '@/lib/graphql';
import { GET_ALL_POSTS } from '@/lib/queries';
import Link from 'next/link';
export const revalidate = 60; // 每 60 秒重新验证
interface Post {
slug: string;
title: string;
excerpt: string;
date: string;
readingTime: string;
featuredImage?: { node: { sourceUrl: string; altText: string } };
categories: { nodes: { slug: string; name: string }[] };
}
export default async function HomePage() {
const data = await client.request(GET_ALL_POSTS, { first: 12 });
const posts: Post[] = data.posts.nodes;
return (
<main className="max-w-6xl mx-auto px-4 py-8">
<h1 className="text-3xl font-bold mb-8">最新文章</h1>
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
{posts.map((post) => (
<article key={post.slug} className="border rounded-lg overflow-hidden shadow-sm hover:shadow-md transition">
{post.featuredImage?.node && (
<img src={post.featuredImage.node.sourceUrl} alt={post.featuredImage.node.altText} className="w-full h-48 object-cover" />
)}
<div className="p-4">
<div className="text-sm text-gray-500 mb-2">
{post.categories.nodes.map(c => c.name).join(', ')} · {post.readingTime}
</div>
<h2 className="text-xl font-semibold mb-2">
<Link href={`/posts/${post.slug}`}>{post.title}</Link>
</h2>
<div className="text-gray-600 line-clamp-3" dangerouslySetInnerHTML={{ __html: post.excerpt }} />
</div>
</article>
))}
</div>
</main>
);
}
3.5 文章详情页（动态路由 + ISR）
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import { client } from '@/lib/graphql';
import { GET_POST_BY_SLUG, GET_ALL_POSTS } from '@/lib/queries';
import { notFound } from 'next/navigation';
export const revalidate = 60;
// 生成静态路径
export async function generateStaticParams() {
const data = await client.request(GET_ALL_POSTS, { first: 100 });
return data.posts.nodes.map((post: { slug: string }) => ({
slug: post.slug,
}));
}
export default async function PostPage({ params }: { params: { slug: string } }) {
try {
const data = await client.request(GET_POST_BY_SLUG, {
slug: params.slug,
});
const { post } = data;
if (!post) return notFound();
return (
<article className="max-w-3xl mx-auto px-4 py-8">
<header className="mb-8">
<h1 className="text-4xl font-bold mb-4" dangerouslySetInnerHTML={{ __html: post.title }} />
<div className="text-gray-500">
{post.author.node.name} · {new Date(post.date).toLocaleDateString('zh-CN')}
</div>
</header>
<div className="prose prose-lg max-w-none" dangerouslySetInnerHTML={{ __html: post.content }} />
</article>
);
} catch {
return notFound();
}
}
四、内容实时更新：Webhook + On-Demand ISR
Headless 架构的一个关键挑战是：WordPress 后台发布或更新文章后，前端的静态页面需要及时刷新。Next.js 提供了 On-Demand ISR（按需增量静态再生）API，配合 WordPress Webhook 即可实现实时更新。
4.1 Next.js 端：Revalidation API
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import { NextRequest, NextResponse } from 'next/server';
export async function POST(request: NextRequest) {
const body = await request.json();
const secret = body.secret;
// 验证 Webhook 签名
if (secret !== process.env.REVALIDATION_SECRET) {
return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
}
try {
const { postSlug } = body;
if (postSlug) {
// 重新验证特定文章页
await revalidatePath(`/posts/${postSlug}`);
}
// 始终重新验证首页（列表已更新）
await revalidatePath('/');
return NextResponse.json({ revalidated: true, now: Date.now() });
} catch (err) {
return NextResponse.json({ message: 'Error revalidating' }, { status: 500 });
}
}
4.2 WordPress 端：配置 Webhook
在 WordPress 中，通过钩子在文章发布或更新时触发 Webhook：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// 跳过自动保存和修订版本
if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) {
return;
}
// 跳过非发布状态
if ($post->post_status !== 'publish') {
return;
}
$webhook_url = 'https://frontend.example.com/api/revalidate';
$secret = defined('REVALIDATION_SECRET') ? REVALIDATION_SECRET : '';
wp_remote_post($webhook_url, [
'body' => json_encode([
'secret' => $secret,
'postSlug' => $post->post_name,
'postId' => $post_id,
'action' => $update ? 'update' : 'publish',
]),
'headers' => ['Content-Type' => 'application/json'],
'timeout' => 10,
]);
}, 10, 3);
五、SEO 优化：Headless 场景下的搜索引擎可见性
Headless 架构的 SEO 是开发者最关心的问题之一。实际上，通过 Next.js 的 SSR/SSG 和完善的 meta 标签配置，Headless 站点的 SEO 表现完全可以媲美甚至超越传统 WordPress 站点。
5.1 使用 Yoast SEO + WPGraphQL Yoast
2
wp plugin install add-wpgraphql-seo --activate
安装后，GraphQL 查询中自动包含 Yoast SEO 字段（如前面的
1 | GET_POST_BY_SLUG |
示例中的
1 | seo |
字段）。然后在 Next.js 中生成 meta 标签：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { Metadata } from 'next';
export async function generateMetadata({ params }: { params: { slug: string } }): Promise<Metadata> {
const data = await client.request(GET_POST_BY_SLUG, { slug: params.slug });
const { seo, title } = data.post;
return {
title: seo?.title || title,
description: seo?.metaDesc || '',
openGraph: {
title: seo?.title || title,
description: seo?.metaDesc || '',
images: seo?.opengraphImage?.sourceUrl
? [seo.opengraphImage.sourceUrl]
: [],
type: 'article',
},
};
}
5.2 生成 Sitemap
使用 Next.js 内置的 Sitemap 生成功能：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { MetadataRoute } from 'next';
import { client } from '@/lib/graphql';
import { gql } from 'graphql-request';
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
const data = await client.request(gql`
query GetSitemapPosts {
posts(first: 1000) {
nodes {
slug
modified
}
}
}
`);
const posts = data.posts.nodes.map((post: any) => ({
url: `https://frontend.example.com/posts/${post.slug}`,
lastModified: new Date(post.modified),
changeFrequency: 'weekly' as const,
priority: 0.8,
}));
return [
{ url: 'https://frontend.example.com', lastModified: new Date(), changeFrequency: 'daily', priority: 1 },
...posts,
];
}
六、生产部署：WordPress 后端 + Next.js 前端
生产环境的部署需要考虑性能、安全和高可用。以下是一个经过验证的部署方案。
6.1 整体架构
2
3
4
5
↓ GraphQL API
WordPress 后端 (Nginx + PHP-FPM)
↓
MySQL 数据库
6.2 WordPress 后端部署要点
- PHP 8.2+：确保性能和兼容性
- OPcache：PHP 字节码缓存，响应时间可降低 50%
- Redis 对象缓存：数据库查询缓存，减少数据库负载
- 限制 API 访问：仅开放 GraphQL 端点，关闭不需要的 REST API 路由
2
3
4
5
6
7
8
9
10
11
12
location /wp-json/ {
# 仅允许前端服务器 IP 访问
allow 10.0.0.0/8;
deny all;
try_files $uri $uri/ /index.php?$args;
}
location /graphql {
# 开放给前端访问
try_files $uri $uri/ /index.php?$args;
}
6.3 Next.js 前端部署
Vercel 是 Next.js 的原生部署平台，一键部署，自动 ISR。对于需要更多控制权的场景，可以使用自托管方案：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]
注意在
1 | next.config.js |
中启用 standalone 输出模式：
2
3
4
5
6
7
8
9
module.exports = {
output: 'standalone',
images: {
remotePatterns: [
{ protocol: 'https', hostname: 'wp.example.com' },
],
},
};
七、常见问题与最佳实践
7.1 富文本内容的安全渲染
WordPress 返回的
1 | content |
字段包含原始 HTML。直接使用
1 | dangerouslySetInnerHTML |
存在 XSS 风险。推荐使用 DOMPurify 进行清洗：
2
3
4
5
6
7
8
9
10
11
12
13
14
15
function SafeContent({ html }: { html: string }) {
const clean = DOMPurify.sanitize(html, {
ALLOWED_TAGS: [
'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
'p', 'a', 'img', 'ul', 'ol', 'li',
'blockquote', 'pre', 'code', 'strong', 'em',
'table', 'thead', 'tbody', 'tr', 'th', 'td',
],
ALLOWED_ATTR: ['href', 'src', 'alt', 'class', 'target', 'rel'],
});
return <div className="prose" dangerouslySetInnerHTML={{ __html: clean }} />;
}
7.2 图片优化
WordPress 媒体库的图片 URL 需要通过 Next.js 的 Image 组件进行优化：
2
3
4
5
6
7
8
9
10
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'wp.example.com',
pathname: '/wp-content/uploads/**',
},
],
}
使用 Next.js
1 | <Image> |
组件替代原生
1 | <img> |
，自动获得懒加载、尺寸优化和 WebP 转换。
7.3 性能监控
建议部署 Web Vitals 监控，持续跟踪 Headless 站点的核心性能指标（LCP、FID、CLS）。可以使用 Vercel Analytics 或自行集成
1 | next/web-vitals |
：
2
3
4
5
6
7
8
9
10
11
12
13
import { Analytics } from '@vercel/analytics/react';
import { SpeedInsights } from '@vercel/speed-insights/next';
export default function RootLayout({ children }) {
return (
<html lang="zh-CN">
<body>{children}</body>
<Analytics />
<SpeedInsights />
</html>
);
}
总结
WordPress Headless CMS 架构不是银弹，但在以下场景中具有明确优势：需要多端内容分发、对前端性能有极致要求、团队更擅长现代前端技术栈、或需要更高的安全保障。实施 Headless 架构需要投入额外的前端开发成本，但带来的灵活性、性能和安全性收益在长期项目中往往是值得的。
关键实施要点回顾：
- WordPress 后端使用 WPGraphQL 替代 REST API，减少数据传输量
- 配置 CORS 和 JWT 认证保障 API 安全
- Next.js 前端使用 ISR 模式兼顾性能和实时性
- Webhook + On-Demand ISR 实现内容发布后秒级更新
- Yoast SEO + Next.js Metadata API 保证 SEO 表现
- DOMPurify 清洗 WordPress 富文本，防范 XSS
- 生产环境通过 CDN + 容器化部署实现高可用
如果你正在考虑将现有 WordPress 站点迁移到 Headless 架构，建议从一个小型内容类型（如博客文章）开始试点，验证前后端协作流程后再逐步扩展到全站。