Headless WordPress چیست؟ آموزش اتصال وردپرس به Next.js

Headless WordPress معماری‌ای است که در آن WordPress مدیریت محتوا، نویسنده، رسانه و گردش انتشار را انجام می‌دهد، اما قالب PHP آن مسئول نمایش نهایی نیست. یک Frontend مستقل مانند Next.js محتوا را از REST API یا GraphQL دریافت و صفحه را برای کاربر Render می‌کند.

در این مدل، WordPress «بدنه» مدیریت محتوا و برنامه Next.js «سر» یا لایه نمایش است. این جداسازی می‌تواند آزادی طراحی، تجربه توسعه مدرن و استقرار مستقل بدهد؛ اما دو سامانه، دو مسیر Deployment و مسئولیت تازه برای Preview، کش، SEO و امنیت ایجاد می‌کند. Headless راه میان‌بُر جادویی برای سریع‌شدن هر سایت نیست.

چرا Headless WordPress اکنون مورد توجه است؟

در Trend Gate ایران در ۹ سپتامبر ۲۰۲۶، WordPress در مقایسه با WooCommerce و Elementor تقاضای بالاتری داشت: میانگین ۹۰روزه آن ۵۵ بود، درحالی‌که WooCommerce عدد ۴ و Elementor عدد ۹ داشت. در بازه ۱۲ماهه نیز WordPress با میانگین ۱۳ جلوتر از دو عبارت دیگر با میانگین ۳ بود.

خود WordPress در این دوره بیشتر «تقاضای پایدار» دارد، اما Related Query عبارت headless wordpress در ایران طی ۱۲ ماه ۱۷۰٪ رشد کرده است. پیشنهادهای واقعی Google نیز نیت‌های with Next.js، React، Astro، setup، examples و hosting را نشان دادند. بنابراین Headless WordPress را می‌توان زیرموضوعی رو‌به‌رشد در یک بازار پایدار دانست؛ نه موجی کوتاه‌مدت.

معماری Headless WordPress چگونه کار می‌کند؟

1. ویرایشگر محتوا در wp-admin نوشته، برگه و رسانه را مدیریت می‌کند.
2. WordPress محتوا را از مسیرهایی مانند /wp-json/wp/v2/posts به‌صورت JSON ارائه می‌دهد.
3. Next.js داده را در Server Component، Route Handler یا مرحله Build دریافت می‌کند.
4. صفحه می‌تواند Static، Dynamic یا با Incremental Revalidation تولید شود.
5. CDN خروجی را نزدیک کاربر Cache می‌کند.
6. با انتشار محتوا، Webhook یا Revalidation زمان‌دار نسخه تازه صفحه را می‌سازد.

REST API هسته WordPress منابعی مانند Posts، Pages، Categories، Tags، Media و Users دارد. داده عمومی را می‌توان بدون احراز هویت خواند؛ عملیات خصوصی و نوشتن محتوا به Authentication و Capability مناسب نیاز دارند.

وردپرس سنتی یا Headless؟

برای وبلاگ یا سایت شرکتی ساده، وردپرس سنتی با Theme سبک اغلب انتخاب اقتصادی‌تری است. Headless زمانی توجیه دارد که چند کانال از یک محتوا استفاده کنند، تیم Frontend تخصصی باشد، تجربه رابط بسیار سفارشی بخواهید یا چرخه انتشار Frontend باید مستقل از CMS باشد.

پیش‌نیازهای پروژه

• یک سایت WordPress با HTTPS و Permalink سالم
• Node.js و یک پروژه Next.js به‌روز
• دسترسی عمومی فقط به داده‌هایی که واقعاً عمومی‌اند
• دامنه جدا یا Subdomain مشخص برای CMS و Frontend
• برنامه Cache، Preview، Image Optimization و Sitemap
• محیط Staging برای آزمون Schema محتوا و Pluginها

برای خواندن Postهای منتشرشده معمولاً Secret لازم نیست. Secret فقط وقتی وارد می‌شود که Draft، Preview یا عملیات Write نیاز دارید. این تفکیک کمک می‌کند Build عمومی به Credential مدیریتی وابسته نباشد.

ساخت پروژه Next.js

یک پروژه TypeScript بسازید و آدرس WordPress را در Environment Variable قرار دهید. در فایل عمومی Client از Credential استفاده نکنید و متغیر حساس را با پیشوند عمومی Framework منتشر نکنید.

npx create-next-app@latest headless-site --ts --app --eslintcd headless-siteprintf 'WORDPRESS_URL=https://cms.example.com\n' > .env.localnpm run dev

در Repository فقط فایلی مانند .env.example با Placeholder نگه دارید. اگر CMS روی دامنه خصوصی است، Build Runner باید دسترسی شبکه کنترل‌شده داشته باشد؛ بازکردن عمومی Admin فقط برای Deploy راه‌حل مناسبی نیست.

خواندن نوشته‌های WordPress با REST API

تابع زیر فقط فیلدهای لازم را درخواست می‌کند، خطای HTTP را کنترل می‌کند و برای داده منتشرشده Revalidation زمان‌دار دارد. محدودکردن _fields حجم Payload را کاهش می‌دهد.

export type WpPost = {  id: number;  slug: string;  date: string;  title: { rendered: string };  excerpt: { rendered: string };}; export async function getPosts(): Promise<WpPost[]> {  const baseUrl = process.env.WORDPRESS_URL;  if (!baseUrl) throw new Error("WORDPRESS_URL is missing");   const url = new URL("/wp-json/wp/v2/posts", baseUrl);  url.searchParams.set("status", "publish");  url.searchParams.set("per_page", "10");  url.searchParams.set("_fields", "id,slug,date,title,excerpt");   const response = await fetch(url, {    next: { revalidate: 300 },    headers: { Accept: "application/json" },  });   if (!response.ok) {    throw new Error(`WordPress failed: ${response.status}`);  }   return (await response.json()) as WpPost[];}

داده rendered ممکن است HTML داشته باشد. آن را بدون سیاست Sanitization در مسیرهای دلخواه Inject نکنید. اگر فقط متن لازم است، در Backend تبدیل امن انجام دهید. برای محتوای غنی، Allowlist تگ و Attributeها، سیاست لینک و تست XSS تعریف کنید.

نمایش فهرست نوشته‌ها در Server Component

import Link from "next/link";import { getPosts } from "@/lib/wordpress"; export default async function HomePage() {  const posts = await getPosts();   return (    <main>      <h1>Latest posts</h1>      <ul>        {posts.map((post) => (          <li key={post.id}>            <Link href={`/blog/${post.slug}`}>              {post.title.rendered}            </Link>          </li>        ))}      </ul>    </main>  );}

برای صفحه جزئیات، Post را با Slug بخوانید و حالت Not Found را صریح مدیریت کنید. در زمان Build، همه Slugها را بدون Pagination دریافت نکنید؛ API هدرهای Pagination دارد و سایت بزرگ باید Batch و Rate Limit را در نظر بگیرد.

کش و Revalidation را چگونه طراحی کنیم؟

کش باید از نیاز انتشار محتوا شروع شود. اگر تأخیر پنج دقیقه پذیرفتنی است، Revalidation زمان‌دار ساده کافی است. اگر انتشار باید فوری دیده شود، WordPress پس از تغییر محتوا یک Webhook امضاشده به Route کنترل‌شده Next.js بفرستد و فقط Tag یا Path مربوط را Revalidate کند.

• Secret Webhook را در Query String و Log قرار ندهید.
• امضا و Timestamp را بررسی کنید تا Replay محدود شود.
• Path یا Tag دریافتی را Allowlist کنید.
• برای شکست Revalidation صف Retry و هشدار داشته باشید.
• CDN و Data Cache را جداگانه مستند کنید.
• پس از انتشار، Smoke Test صفحه و Metadata انجام دهید.

پاک‌کردن کل Cache برای هر ویرایش ساده است اما در سایت پرترافیک می‌تواند موج درخواست به WordPress بسازد. Invalidation دقیق، فشار Backend و زمان پاسخ را قابل‌کنترل نگه می‌دارد.

Preview نوشته‌های Draft

Preview از خواندن محتوای عمومی حساس‌تر است. درخواست باید کاربر مجاز را احراز هویت کند، یک Token کوتاه‌عمر و تک‌مصرف داشته باشد و فقط همان Post را نمایش دهد. WordPress از Application Passwordهای قابل لغو برای دسترسی API پشتیبانی می‌کند؛ آن‌ها برای Login تعاملی نیستند و باید فقط روی HTTPS استفاده شوند.

برای هر Integration یک User کم‌اختیار و Application Password جدا بسازید. Credential را در Server Environment نگه دارید، هرگز به Browser Bundle نفرستید، زمان استفاده را مانیتور و پس از خروج Integration لغو کنید. رمز اصلی Administrator را برای REST API استفاده نکنید.

SEO در معماری Headless

• Title، Description، Canonical و Robots را در Frontend تولید کنید.
• Sitemap و RSS باید از همه محتوای Published آگاه باشند.
• Slug، Redirect و تاریخ انتشار هنگام Migration حفظ شوند.
• Open Graph و تصویر اشتراک‌گذاری برای هر Post تنظیم شود.
• Structured Data بر اساس نوع محتوا و داده معتبر ساخته شود.
• صفحه‌های Preview و محیط Staging حتماً noindex باشند.
• خطاهای API نباید صفحه خالی با HTTP 200 تولید کنند.

بسیاری از Pluginهای SEO Metadata را در WordPress ذخیره می‌کنند، ولی نمایش آن در Headless خودکار نیست. بررسی کنید Plugin داده لازم را از API ارائه می‌دهد یا یک Endpoint محدود برای Metadata بسازید. خروجی Frontend باید با ابزارهای تست Schema و Crawl واقعی بررسی شود.

تصویر و رسانه

WordPress اطلاعات Media را از REST API می‌دهد، اما Frontend باید Domain تصویر را Allowlist، اندازه مناسب را انتخاب و نسبت ابعاد را ثابت کند تا Layout Shift رخ ندهد. برای Alt Text از فیلد واقعی رسانه استفاده کنید و نام فایل را جایگزین توضیح انسانی نکنید.

اگر CDN تصویر دارید، URL، Cache-Control و سیاست پاک‌سازی را مشخص کنید. Upload مستقیم از Browser به WordPress نیازمند Authentication و محدودیت نوع و اندازه فایل است؛ برای سایت محتوایی عادی بهتر است Upload همچنان در پنل WordPress باقی بماند.

امنیت Headless WordPress

1. پنل و API نوشتن را پشت HTTPS و Rate Limit نگه دارید.
2. Endpointهای عمومی را فقط به داده Published محدود کنید.
3. Application Password جدا، قابل لغو و کم‌اختیار بسازید.
4. Secretها را فقط در Server نگه دارید.
5. HTML دریافتی را با سیاست روشن Sanitization نمایش دهید.
6. WordPress Core و Pluginها را به‌روز و سطح حمله را کم کنید.
7. CORS را جای Authorization تلقی نکنید.
8. Log دسترسی و خطا را بدون ذخیره Secret نگه دارید.

جداشدن Frontend به‌تنهایی WordPress را امن نمی‌کند. CMS هنوز باید Patch، Backup و Monitor شود. همچنین مخفی‌کردن آدرس CMS دفاع اصلی نیست؛ کنترل دسترسی، نسخه‌به‌نسخه ارتقا و کمینه‌کردن Pluginها مؤثرتر است.

هزینه‌های پنهان Headless

Plugin Compatibility

Pluginهایی که Shortcode، فرم، Search، عضویت یا خروجی Theme می‌سازند ممکن است در Frontend مستقل کار نکنند. پیش از Migration، فهرست قابلیت‌ها را تهیه و هزینه بازپیاده‌سازی هرکدام را برآورد کنید.

Preview و تجربه ویرایشگر

ویرایشگر انتظار دارد قبل از انتشار، خروجی واقعی را ببیند. Preview کند یا ناپایدار باعث دورزدن فرایند می‌شود. Preview را یک Feature اصلی بدانید، نه کار پایانی.

دو Pipeline و دو نقطه شکست

وردپرس سالم با Build شکست‌خورده، یا Frontend سالم با API کند هر دو تجربه ناقص می‌سازند. Monitoring باید CMS، Build، Webhook، Cache و صفحه عمومی را جدا بسنجد.

چک‌لیست تصمیم‌گیری

• آیا رابط کاربری واقعاً خارج از توان Theme مناسب است؟
• آیا تیم تجربه کافی در Next.js و عملیات دو سرویس دارد؟
• آیا چند کانال از محتوای یکسان استفاده می‌کنند؟
• آیا بودجه Preview، Search، فرم و SEO بازپیاده‌سازی شده است؟
• آیا زمان قابل قبول انتشار تا نمایش مشخص است؟
• آیا Pluginهای حیاتی API مناسب دارند؟
• آیا Migration URL و Redirectها طراحی شده‌اند؟
• آیا مالکیت امنیت و Backup هر دو سامانه روشن است؟

اگر بیشتر پاسخ‌ها منفی است، وردپرس سنتی بهینه‌شده احتمالاً انتخاب بهتر است. معماری خوب، پیچیده‌ترین معماری نیست؛ کم‌هزینه‌ترین ساختاری است که نیاز واقعی محصول را با کیفیت برآورده می‌کند.

جمع‌بندی

Headless WordPress امکان می‌دهد Workflow آشنای تولید محتوا را با Frontend مدرن ترکیب کنید. REST API هسته برای شروع کافی است و Next.js می‌تواند صفحه‌های سریع و Cacheشده تولید کند. موفقیت پروژه اما به Preview امن، Revalidation دقیق، SEO کامل، Sanitization و برنامه نگه‌داری دو سامانه وابسته است.

برای سایت ساده، Theme سبک انتخاب منطقی‌تری است؛ برای محصول چندکاناله یا رابط بسیار سفارشی، Headless می‌تواند ارزشمند باشد. قبل از Migration یک Proof of Concept بسازید، هزینه Pluginها و Preview را اندازه بگیرید و فقط بعد تصمیم نهایی بگیرید.

پیش از ارتقای CMS، چک‌لیست ارتقای امن WordPress را مرور کنید. برای تکمیل Metadata و نمایش در نتایج جدید گوگل نیز راهنمای SEO برای AI Overviews و AI Mode مفید است.

برای یادگیری WordPress، JavaScript و ساخت پروژه‌های مدرن وب، مسیرهای آموزشی خانه برنامه‌نویسان البرز را بررسی کنید.