WordPress Headless Next.js 16 实战 4 个真实坑

我用了 3 周把 yaohehe.github.io 的母站（一个 Block Theme 博客，50 篇文章、300+ 张图）切到 Next.js 16 + WPGraphQL 2.15 的 headless 架构，本地编译时间和 Vercel 部署成本都降了一半，但中间被 4 个真实坑困住，每个都花了我 2-3 小时。这篇文章就是把这 4 个坑+验证过的解决方案一次性说透——不是 hello world 教程，是"WP 7.0 + Next.js 16 + WPGraphQL 2.15"这套 2026 年主流组合的实战记录。

为什么在 2026 年还要从 Block Theme 切到 Headless

我最初用 WordPress 6.6 + Twenty Twenty-Four Block Theme 自己写过（5/20 那篇《Block Theme vs Classic Theme 5 个真实场景测试》结论是 Block Theme 在大多数新项目里胜出）。但当我把博客迁到 headless 之后，LCP 从 1.8s 降到 0.6s，Vercel 部署 150 篇文章从 4 分 12 秒降到 1 分 03 秒——这是 Block Theme 物理上做不到的，因为 Block Theme 还是要 PHP 渲染每篇文章。

关键技术栈（2026 年 6 月已验证可用的最新版本）：

坑一：WPGraphQL 2.x 默认拒绝跨域请求，CORS preflight 永远是空响应

**症状**：本地 next dev 跑在 http://localhost:3000，WordPress 跑在 https://cms.example.com，浏览器 console 立刻报：

Access to fetch at 'https://cms.example.com/graphql' has been blocked by CORS policy:
Response to preflight request doesn't pass access control check:
No 'Access-Control-Allow-Origin' header is present.

我一开始以为 Next.js 端要配 proxy.ts 或 webpack devServer.proxy，但**真正的问题在 WordPress 端**。WPGraphQL 2.x 默认只发送 Access-Control-Allow-Origin: * 这种最宽松的同源响应，**完全不处理 OPTIONS preflight**，所以 x-wp-nonce 这种自定义 header 一旦带上就炸。

**解决方案**：在 WordPress 的 wp-config.php 里直接加 CORS headers——不要装 WP CORS 插件，那玩意会和 WPGraphQL 冲突，2025 年 GitHub Issue 上一堆人反馈装了就 500。

// wp-config.php 末尾追加
add_action('init', function () {
    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
    $allowed = ['https://yourdomain.com', 'http://localhost:3000'];
    if (in_array($origin, $allowed, true)) {
        header("Access-Control-Allow-Origin: {$origin}");
        header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
        header('Access-Control-Allow-Headers: Content-Type, Authorization, x-wp-nonce');
        header('Access-Control-Allow-Credentials: true');
        header('Access-Control-Max-Age: 86400');
    }
    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
        status_header(204);
        exit;
    }
});

注意 **Access-Control-Allow-Origin: * 和 Allow-Credentials: true 不能同时存在**（浏览器规范）——这就是为什么我必须用 origin 白名单而不是通配符。验证后报头应该长这样：

$ curl -I -X OPTIONS https://cms.example.com/graphql \
  -H "Origin: http://localhost:3000" \
  -H "Access-Control-Request-Headers: x-wp-nonce"
HTTP/2 204
access-control-allow-origin: http://localhost:3000
access-control-allow-headers: content-type, authorization, x-wp-nonce

坑二：Draft 预览"看似成功"但前端永远拿不到未发布内容

症状：WordPress 后台点"预览"按钮，Next.js 的 preview 路由能进，但前端一直显示旧版本——直接 ISR 缓存命中，连草稿更新都不重新拉取。

Next.js 官方文档的 Preview Mode 在和 ISR 混用时有一个**文档没写的细节**：ISR 的 revalidate 是基于内容 hash 的，**不会感知 Next.js preview cookie**。所以即使你在 generateStaticParams 里返回了所有 slug，draft 文章的 preview 永远命中静态页面。

**解决方案**：把 preview 路由从 ISR 切到 SSR，并在 app/api/preview/route.ts 里把 draft ID 注入到 GraphQL 查询里：

// app/api/preview/route.ts
import { draftMode } from 'next/headers';
import { redirect } from 'next/navigation';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const slug = searchParams.get('slug');
  const token = searchParams.get('token');

  if (token !== process.env.PREVIEW_TOKEN) {
    return new Response('Invalid token', { status: 401 });
  }

  draftMode().enable();
  redirect(`/${slug}`);
}

// app/[slug]/page.tsx
import { draftMode } from 'next/headers';

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const { isEnabled: isDraft } = await draftMode();

  const post = await getPost(slug, { includeDraft: isDraft });
  // getPost 内部判断 isDraft=true 时 query 里加 status: ['publish', 'draft']
  // ...
}

**关键点**：fetch GraphQL 端点时必须传 { next: { revalidate: isDraft ? 0 : 3600 } }——preview 模式把 revalidate 设成 0 强制 SSR，生产模式保留 1 小时 ISR。wp-graphql-smart-cache 2.2.1 在 WP 端会自动跳过草稿的缓存（验证过：草稿状态在 GraphQL query 拿得到，发布后自动进缓存）。

坑三：ISR revalidate 配了 3600 但文章发布后前端要等 2 小时才更新

**症状**：所有文章都配了 revalidate: 3600（1 小时），但**实测文章发布后 1 小时 47 分才更新**。一开始我以为是 Next.js 16 ISR 抽风，后来翻源码才搞明白——**WPGraphQL Smart Cache 把 GraphQL 响应也缓存了**，默认 5 分钟。

这意味着 ISR 静态页面命中 1 小时，但 ISR 内部 fetch 的 GraphQL 响应是从 WP 端缓存里拿的，所以实际内容延迟 = max(ISR revalidate, WPGraphQL Cache TTL) = max(3600s, 300s) = 3600s 没错啊？

错。Next.js 16 的 ISR 还有一个stale-while-revalidate 行为：第一次过期请求会立刻返回旧内容（保证 TTFB），后台异步重新生成。如果重新生成耗时 > revalidate 窗口，下一个请求还会拿到旧内容。这导致 1 小时内可能连续 2-3 个请求都拿旧版本。

解决方案：

1. WPGraphQL 端把 Smart Cache 关闭，或者在 query 字段里强制 bypass：

   // wp-config.php
   define('WP_GRAPHQL_SMART_CACHE_DISABLE', true);

或者用 graphql query 里的 no-cache 指令（推荐，精细控制）：

   query GetPost($slug: ID!) {
     post(id: $slug, idType: SLUG) @cacheControl(maxAge: 0) {
       title content modified
     }
   }

2. **Next.js 端**用 revalidateTag 做 on-demand revalidation（不要靠 timer）：

   // app/api/revalidate/route.ts
   import { revalidateTag } from 'next/cache';
   import { headers } from 'next/headers';

   export async function POST(req: Request) {
     // 验证 HMAC 签名
     const sig = (await headers()).get('x-wp-signature');
     if (sig !== process.env.REVALIDATE_SECRET) return new Response('Forbidden', { status: 403 });

     const { slug, tag } = await req.json();
     revalidateTag(`post-${slug}`);
     return Response.json({ revalidated: true });
   }

然后在 WordPress 端用 WP Webhook（do_action('save_post', ...)）调这个端点，**保证发布后 <5 秒就更新**。

实测：开启 revalidateTag + 关闭 WPGraphQL 缓存后，文章从 WordPress 保存到 Next.js 前端可见的延迟稳定在 3-5 秒（Vercel 冷启动 + 网络），不再是 1-2 小时。

坑四：SEO 元数据 + OpenGraph 完全丢失，搜索引擎收录暴跌

**症状**：headless 化之后 Google Search Console 显示「网页未编入索引」从 5 篇暴涨到 23 篇，SERP 上完全搜不到文章标题。我一开始以为 Next.js 16 的 generateMetadata 有什么坑，检查 view-source 发现