خطای عدم نمایش هدر در قالب وردپرس
آیا هدر قالب وردپرستان ناپدید شده یا فقط در بعضی صفحات دیده نمی‌شود؟ این راهنما دوازده علت ریشهای — از فراخوانی نشدن get_header تا کش و تعارض صفحه‌ساز — را با الگوی عیب‌یابی گام‌به‌گام بررسی می‌کند.
هدر ناپدید شده، یکی از آن خطاهایی است که در نگاه اول ساده به نظر می‌رسد ولی می‌تواند ساعت‌ها وقت ببرد. اولین باری که با این مشکل روبه‌رو شدم، در یک پروژه شرکتی بود: هدر در صفحه اصلی می‌آمد، ولی در صفحات داخلی نبود. آن روز فهمیدم مسئله در قالب والد نیست، در ساختار فراخوانی تمپلیت است. از آن به بعد، هر بار که هدر یا فوتر غایب می‌شود، مسیر مشخصی را در ذهنم مرور می‌کنم که در این مقاله بازش کرده‌ام.
چرا هدر قالب به‌سادگی ناپدید می‌شود؟
هدر یا همان بخش بالای سایت، در معماری قالب‌های وردپرس یک قرارداد مشخص دارد: در فایل header.php تعریف می‌شود و در هر تمپلیت با تابع get_header() فراخوانی می‌شود. این لایه‌بندی ساده است ولی به همان اندازه، شکننده. اگر یکی از دو طرف این قرارداد — تعریف یا فراخوانی — از قلم بیفتد، هدر ناپدید می‌شود. اگر با مفهوم لایه‌ای قالب آشنا نیستید، پیشنهاد می‌کنم ابتدا قالب وردپرس چیست و چگونه انتخاب کنیم را بخوانید تا ساختار کلی قالب را در ذهن داشته باشید.
مسئله دومی که هدر را شکننده می‌کند این است که هدر معمولاً فقط فایل PHP نیست؛ بخشی از آن در CSS، بخشی در توابع PHP و بخشی هم در کلاس‌های بدنه تعریف می‌شود. مثلاً اگر کلاس elementor-default روی بدنه اضافه شده باشد و CSS شما آن را مخفی کند، هدر در ظاهر ناپدید می‌شود در حالی که در کد HTML کاملاً سالم است. همین چندلایه بودن، عیب‌یابی را گاهی گیج‌کننده می‌کند.
هدر قالب مثل درِ ورودی یک خانه است؛ اگر بسته نشود، ممکن است فقط در بعضی اتاق‌ها و نه همه‌شان باز باشد — که نشان می‌دهد مشکل در قرارداد لایه است، نه در خودِ در.
الگوی عیب‌یابی که در پروژه‌ها دنبال می‌کنم
پیش از فهرست علت‌ها، بگذارید الگویی را بگویم که خودم در همه پرونده‌های هدر ناپدیدشده طی می‌کنم. این الگو، مرحله‌ای است و در هر گام نیمی از مظنون‌ها حذف می‌شوند:
- اول با View Source در مرورگر بررسی می‌کنم که آیا کد HTML هدر اصلاً در صفحه هست یا نه. اگر هست ولی دیده نمی‌شود، مسئله ظاهری است نه ساختاری.
- اگر HTML هدر نیست، سراغ فایل
header.phpقالب فعال می‌روم و مطمئن می‌شوم درست وجود دارد و خراب نیست. - در تمپلیت صفحه‌ای که مشکل دارد، بررسی می‌کنم که
get_header()فراخوانی شده باشد. - سپس کش مرورگر، کش افزونه و کش سرور را پاک می‌کنم.
- اگر هنوز مشکل بود، سراغ تعارض افزونه یا صفحه‌ساز می‌روم.
در نود درصد پرونده‌های واقعی، مقصر در یکی از سه گام اول مشخص می‌شود. بقیه موارد به تعارض یا کش برمی‌گردد. مسیر کامل و روش تشخیص هر لایه در عیب‌یابی خطای قالب وردپرس به‌طور سیستماتیک آمده است.
علت اول: فراخوانی نشدن get_header()
شایع‌ترین علت هدر ناپدیدشده، ساده‌ترین علت هم هست: در فایل تمپلیت آن صفحه، تابع get_header() فراخوانی نشده است. این اتفاق وقتی می‌افتد که یک فایل تمپلیت جدید ساخته شده — مثلاً برای یک page template سفارشی — و توسعه‌دهنده کد را از جایی کپی کرده که در آن get_header() نبوده. راه‌حل، اضافه کردن این خط در ابتدای همان فایل تمپلیت است:
<?php
get_header();
?>ترتیب مهم است: get_header() باید قبل از هر خروجی دیگری باشد. اگر بعد از <!DOCTYPE html> بیاید، ممکن است کار کند ولی توصیه نمی‌شود، چون استاندارد وردپرس این ترتیب را نمی‌پسندد. اگر مطمئن نیستید که تمپلیت فعلی چیست، پیشنهاد می‌کنم با افزونه Query Monitor یا ابزار Debug Bar ببینید کدام فایل تمپلیت اجرا می‌شود. مسیر دقیق تشخیص تمپلیت و ساختار آن در رفع خطای Template file missing باز شده است.
علت دوم: فایل header.php گم‌شده یا خراب
اگر فایل header.php در پوشه قالب شما وجود نداشته باشد یا نامش تغییر کرده باشد، فراخوانی get_header() بی‌اثر می‌شود و هدر ناپدید می‌شود. این مسئله معمولاً بعد از مهاجرت یا آپدیت قالب پیش می‌آید: پوشه‌ای جایگزین شده و فایلی که در نسخه قبلی وجود داشت، در نسخه جدید اسمش عوض شده یا ساختار تغییر کرده.
راه تشخیص: از طریق FTP یا File Manager هاست، پوشه قالب فعال را باز کنید و ببینید آیا فایل header.php وجود دارد و حجمش صفر نیست. اگر فایل خالی است یا حجم بسیار کمی دارد، احتمالاً آپلود یا جایگزینی ناقص بوده. راه‌حل: نسخه سالم را از مخزن سازنده دانلود و جایگزین کنید. اگر با مفهوم ساختار فایل قالب آشنا نیستید، این موضوع در رفع خطای قالب وردپرس به‌طور گام‌به‌گام توضیح داده شده است.
علت سوم: ساختار نادرست قالب چایلد
اگر از قالب Child (فرزند) استفاده می‌کنید و آن قالب ناقص ساخته شده، هدر ممکن است ناپدید شود. الگوی شایع: توسعه‌دهنده یک Child Theme می‌سازد ولی فایل style.css آن به‌درستی والد را معرفی نمی‌کند یا خط Template: را اشتباه می‌نویسد. نتیجه این می‌شود که وردپرس، فایل‌های والد را نمی‌بیند و اگر هدر در فرزند بازنویسی نشده باشد، هیچ فایلی برای نمایش پیدا نمی‌شود.
راه‌حل: هدر style.css فرزند را بازبینی کنید. این خط باید دقیقاً نام پوشه والد را داشته باشد:
/*
Theme Name: My Child
Template: twenty-twenty-one
*/اگر Template اشتباه باشد، وردپرس قالب فرزند را نمی‌شناسد و رفتارهای عجیبی از خودش نشان می‌دهد. توضیحات کامل ساختار Child Theme در قالب چایلد وردپرس چیست آمده است.
قالب فرزندی که والدش را درست معرفی نکند، یک فرزند یتیم است؛ نه از پدر ارث می‌برد، نه مستقل کار می‌کند.
علت چهارم: منطق شرطی که هدر را مخفی می‌کند
گاهی هدر در HTML صفحه هست ولی با یک شرط خاص مخفی می‌شود. مثال رایج: قالب در header.php شرطی گذاشته که هدر در صفحات خاصی مثل صفحه فرود یا حالت امتحان (Maintenance Mode) نمایش داده نشود. این نوع شرط معمولاً به‌شکل زیر نوشته می‌شود:
<?php
if ( ! is_page_template( 'template-landing.php' ) ) {
// show header
}
?>اگر تمپلیت صفحه شما با این شرط یکی است، هدر مخفی می‌شود و شما فکر می‌کنید مشکل فنی دارید. راه‌حل: فایل header.php را باز کنید و کل کد را یک بار با دقت بخوانید. اگر شرطی هست، آن را موقتاً کامنت کنید و تست کنید. این نوع خطا در قالب‌های فروشگاهی و شرکتی که گاهی صفحات خاص دارند بیشتر دیده می‌شود. اگر می‌خواهید شرط را دقیق‌تر بشناسید، مقاله دیباگ خطای قالب وردپرس روش خوبی برای ردیابی این نوع منطق ارائه می‌دهد.
علت پنجم: تعارض با صفحه‌ساز یا قالب بلوکی
اگر از صفحه‌سازهایی مثل Elementor، Divi Builder یا WPBakery استفاده می‌کنید، هرکدام از این‌ها می‌توانند هدر قالب را بازنویسی کنند. الگوی شایع: صفحه‌ساز در تنظیمات صفحه، گزینه‌ای با نام Canvas یا Blank Template را فعال کرده که هدر و فوتر قالب را کاملاً حذف می‌کند و به‌جای آن هدر مخصوص خودش را نمایش می‌دهد. اگر آن هدر مخصوص به‌دلایلی بارگذاری نشود، کاربر به‌کل بدون هدر می‌ماند.
راه‌حل: در تنظیمات همان صفحه، گزینه قالب صفحه را به مقدار پیش‌فرض قالب برگردانید. اگر می‌خواهید بفهمید صفحه‌سازها چطور روی هدر اثر می‌گذارند، بررسی نقاط قوت و ضعف المنتور تصویر روشنی می‌دهد. برای ساختمان سایت بلوکی در وردپرس، الگوی سربرگ معمولاً از طریق theme.json و سایت ویرایشگر تعریف می‌شود؛ نه از header.php. یعنی اگر قالب بلوکی است ولی شما به دنبال فایل PHP می‌گردید، اصلاً فایلی نیست چون هدر از داخل سایت ویرایشگر مدیریت می‌شود.
علت ششم: تعارض افزونه‌ای که روی get_header اثر می‌گذارد
بعضی افزونه‌ها به‌طور ناخواسته روی هوک get_header اثر می‌گذارند. مثال‌های واقعی: افزونه‌های امنیتی که در حالت فایروال، بعضی بخش‌های خروجی را حذف می‌کنند؛ افزونه‌های کش که HTML را ناقص ذخیره می‌کنند؛ افزونه‌های بهینه‌سازی که CSS هدر را در بسته‌بندی حذف می‌کنند. راه تشخیص: همه افزونه‌ها را در محیط استجینگ خاموش کنید و یکی‌یکی روشن کنید تا مقصر مشخص شود.
روش سیستماتیک این عیب‌یابی در رفع خطای تضاد افزونه‌ها در وردپرس آمده و فهرست افزونه‌های حساس به این نوع رفتار در تأثیر افزونه‌ها بر سرعت سایت بررسی شده است.
علت هفتم: کش مرورگر یا کش سرور
این علت واقعاً ساده است ولی در عمل شایع و گیج‌کننده. شما هدر را در کد درست کرده‌اید، ولی مرورگر نسخه قدیمی صفحه را نشان می‌دهد. یا افزونه کش، نسخه خراب قبلی را در حافظه نگه داشته و همان را می‌دهد. علت سوم، CDN (Content Delivery Network یا شبکه توزیع محتوا) است که نسخه قدیمی را در سراسر دنیا نگه می‌دارد.
راه‌حل: به‌ترتیب زیر عمل کنید:
- اول کش مرورگر را با
Ctrl + Shift + Rپاک کنید. - دوم کش افزونه کش را از پنل آن پاک کنید.
- سوم اگر CDN دارید، کش آن را هم پاک کنید.
- چهارم سایت را در حالت ناشناس مرورگر باز کنید.
اگر در حالت ناشناس هدر هست ولی در حالت عادی نیست، مسئله کاملاً کش مرورگر است. مسیر کامل پاک‌سازی هر سه لایه در بهترین افزونه‌های کش وردپرس آمده است.
علت هشتم: پنهان‌شدن با CSS یا کلاس بدنه
این علت را در فهرست گذاشتم چون بارها دیده‌ام که توسعه‌دهنده ساعت‌ها وقت صرف عیب‌یابی PHP کرده و نهایتاً کشف کرده که CSS مسئول است. الگو: قالب با یک کلاس خاص مثل elementor-default یا single-post روی بدنه، CSSای را اجرا می‌کند که هدر را مخفی می‌کند. مثلاً:
body.single-post .site-header {
display: none;
}راه تشخیص سریع: در Chrome DevTools، روی هدر راست‌کلیک کنید (اگر وجود داشته باشد) و گزینه Inspect را بزنید. تب Styles را باز کنید و ببینید کدام قاعده CSS روی آن اعمال شده. اگر چیزی هدر را مخفی می‌کند، در همان‌جا می‌بینید. راه‌حل: قاعده CSS را از Child Theme بازنویسی کنید، نه از قالب والد. این کار را با الگوی گفته‌شده در قالب چایلد وردپرس انجام دهید تا در آپدیت بعدی از بین نرود.
علت نهم: مجوز فایل و خواندن ناپذیر بودن header.php
اگر مجوز فایل header.php روی ۶۰۰ باشد ولی سرور PHP با کاربر متفاوتی اجرا شود، فایل خوانده نمی‌شود و هدر ناپدید می‌شود. این مسئله معمولاً بعد از مهاجرت یا تنظیمات دستی مجوزها پیش می‌آید. نشانه‌اش این است که هدر در همه صفحات ناپدید می‌شود ولی هیچ خطای PHP هم داده نمی‌شود؛ فقط هدر نیست.
راه تشخیص: از طریق FTP، مجوز پوشه قالب و فایل‌های داخلش را نگاه کنید. مجوز استاندارد پوشه‌ها ۷۵۵ و فایل‌ها ۶۴۴ است. اگر متفاوت بود، اصلاحش کنید. توضیح کامل این دسته از خطاها در خطای دسترسی به فایل‌ها در وردپرس آمده است.
علت دهم: کد سفارشی در functions.php
اگر شما یا کسی قبل از شما در فایل functions.php کدی اضافه کرده که روی get_header اثر می‌گذارد، هدر ممکن است ناپدید شود. مثال رایج: کدی که برای صفحات خاص، هدر را حذف می‌کند یا آن را به لایه‌ای دیگر منتقل می‌کند. همچنین اگر در functions.php یک خطای کشنده وجود داشته باشد، ممکن است کل سایت از کار بیفتد ولی خطا آن‌قدر ساکت باشد که فقط هدر ناپدید شود و بقیه سالم بماند.
راه تشخیص: کد functions.php قالب والد و فرزند را با دقت مرور کنید. اگر کدی نیست، از طریق همان روش دیباگ، خطاهای احتمالی را ببینید. اگر کدی سفارشی اضافه کرده‌اید، همیشه بهتر است آن را در Child Theme نگه دارید. مثال‌های رایج اشتباهات کدنویسی در اشتباهات رایج در توسعه وردپرس آمده است.
علت یازدهم: هدر قالب‌های ووکامرسی و برگه‌های خاص
در فروشگاه‌های ووکامرس، بعضی تمپلیت‌ها مثل صفحه پرداخت، سبد خرید و برخی صفحات حساب کاربری، عمداً هدر قالب را حذف می‌کنند تا کاربر روی فرآیند خرید تمرکز کند. اگر بدون علم به این موضوع، هدر را از دست‌رفته می‌بینید، ممکن است رفتار عمدی ووکامرس باشد. راه‌حل: تنظیمات ووکامرس و تمپلیت‌های فروشگاهی را در Child Theme بازنویسی کنید تا هدر در این صفحات هم نمایش داده شود.
مسیر دقیق این کار در سفارشی‌سازی سبد خرید و تسویه‌حساب ووکامرس آمده و اگر هدر در سایر صفحات فروشگاه هم ناپدید می‌شود، خطای قالب در ووکامرس نقطه شروع بهتری است.
علت دوازدهم: آپدیت قالب و تغییر ساختار فایل
گاهی هدر بعد از یک آپدیت قالب ناپدید می‌شود. علت معمولاً این است که قالب جدید ساختار متفاوتی برای هدر دارد: مثلاً در نسخه قبلی header.php در ریشه قالب بود و در نسخه جدید در پوشه template-parts جابه‌جا شده. اگر شما فایل قبلی را ویرایش کرده بودید و اکنون آن تغییرات جای دیگری لازم است، هدر می‌تواند در ظاهر ناپدید شود.
راه‌حل: نسخه قبلی قالب را از بکاپ پیدا کنید، فایل header.php را با نسخه جدید مقایسه کنید و تفاوت‌ها را در Child Theme اعمال کنید. مسیر کامل این نوع مقایسه و بازگردانی در خطای بروزرسانی قالب وردپرس آمده است. یک توصیه عملی: قبل از هر آپدیت قالب، از فایل‌های ویرایش‌شده یک diff تهیه کنید و آن را در Child Theme پیاده کنید.
هر بار که هدر قالب ناپدید می‌شود، در واقع یک لایه از قرارداد معماری شما شکسته است. اولین گام همیشه پیدا کردن همان لایه شکسته است، نه تعمیر حدسی همه‌چیز.
روش تست مرحله‌ای که در پروژه‌ها استفاده می‌کنم
بعد از این همه سال، ترتیب شخصی‌ام برای عیب‌یابی هدر ناپدیدشده یک الگوی ثابت دارد:
- ابتدا با View Source چک می‌کنم که HTML هدر اصلاً در صفحه وجود دارد یا نه.
- اگر HTML هست ولی نمایش داده نمی‌شود، سراغ DevTools و تب Styles می‌روم.
- اگر HTML نیست، تمپلیت صفحه را می‌شناسم و در آن
get_header()را چک می‌کنم. - اگر
get_header()هست ولی هدر نمایش داده نمی‌شود، سراغ فایلheader.phpمی‌روم. - حالت دیباگ را روشن می‌کنم و لاگ را بررسی می‌کنم.
- اگر همه‌چیز در کد سالم بود، کش‌ها را پاک می‌کنم.
- در گام آخر، اگر مشکل باقی است، افزونه‌ها را در استجینگ دسته‌ای خاموش می‌کنم.
این ترتیب، از ساده به پیچیده حرکت می‌کند و تقریباً همیشه در چند دقیقه جواب می‌دهد. اگر با مفهوم لایه‌بندی قالب آشنایی بیشتری می‌خواهید، قالب وردپرس چیست و چگونه انتخاب کنیم را یک بار دیگر مرور کنید و مسیر تست قالب را در بهترین روش تست قالب وردپرس جدی بگیرید.
سه عادت پیشگیرانه
سه عادت که بیشترین اثر را روی کاهش این دسته از خطاها داشته‌اند:
اول، هیچ‌وقت فایل header.php قالب والد را ویرایش نمی‌کنم. هر تغییری روی هدر را در Child Theme می‌گذارم. این یک قاعده شخصی است که از تجربه‌های تلخ سال‌های اول کارم شکل گرفت.
دوم، بعد از هر آپدیت قالب، سه صفحه کلیدی سایت (خانه، یک نوشته، یک صفحه داخلی) را باز می‌کنم و هدر و فوتر را چک می‌کنم. این عادت کوتاه، جلوی بیشتر سردرگمی‌های چند روز بعد را می‌گیرد.
سوم، اگر صفحه‌ساز استفاده می‌کنم، هیچ‌وقت از گزینه Blank Template یا Canvas بدون آگاهی از پیامدهایش استفاده نمی‌کنم. این نوع تمپلیت‌ها به‌طور کامل هدر و فوتر را حذف می‌کنند و اگر اشتباه انتخاب شوند، ساعت‌ها سردرگمی ایجاد می‌کنند.
نگاه عمیق‌تر: هدر به‌عنوان قرارداد معماری
برای مهندسانی که با معماری نرم‌افزار سروکار دارند، ارزش دارد هدر قالب را به‌عنوان یک قرارداد معماری (Architectural Contract) نگاه کنند، نه یک فایل تک. در وردپرس، قرارداد این است که هر تمپلیت با get_header() شروع می‌شود و با get_footer() تمام می‌شود. این قرارداد به‌ظاهر بدیهی است، ولی وقتی تیم‌ها بزرگ می‌شوند و چند توسعه‌دهنده روی یک پروژه کار می‌کنند، شکستن این قرارداد به یک پرونده عیب‌یابی پیچیده تبدیل می‌شود.
سه مشاهده دقیق‌تر از تجربه‌های میدانی: اول، در قالب‌های بلوکی، مفهوم هدر از یک فایل PHP به یک بخش قابل ویرایش در سایت ویرایشگر منتقل شده. این یعنی اگر با قالب‌های بلوکی کار می‌کنید، دیگر نباید دنبال header.php بگردید؛ هدر در پوشه parts قالب تعریف می‌شود و از طریق ویرایشگر بلوک مدیریت می‌شود. اگر این تفاوت را ندانید، ممکن است ساعت‌ها در پوشه اشتباه دنبال فایل باشید.
دوم، در معماری Headless که فرانت‌اند جدا از وردپرس سرو می‌شود، مفهوم هدر قالب کاملاً از بین می‌رود. اینجا هدر به یک کامپوننت React یا Vue تبدیل می‌شود که از وردپرس فقط داده می‌گیرد. اگر در چنین پروژه‌ای با ناپدید شدن هدر مواجه شوید، مسئله در کد فرانت‌اند است نه در قالب وردپرس.
سوم، در پروژه‌های چندسایتی (Multisite)، امکان متفاوت بودن قالب برای هر سایت شبکه وجود دارد. اگر روی یکی از سایت‌های شبکه، هدر را تغییر دهید ولی روی سایت دیگری نه، ممکن است هدر ناپدید شود بدون این که کسی متوجه شود. این الگو در پروژه‌های سازمانی با چند زیرسایت شایع‌تر است و نیاز به مدیریت دقیق قالب در سطح شبکه دارد.
چهارم، در CI/CD (Continuous Integration / Continuous Deployment یا یکپارچه‌سازی و استقرار پیوسته)، اگر قالب از طریق مخزن کد استقرار داده شود ولی فایل header.php به‌اشتباه در فایل .gitignore باشد، بعد از هر استقرار، هدر ناپدید می‌شود. این نوع خطا در تجربه من، همیشه چند استقرار طول می‌کشد تا کشف شود، چون در محیط توسعه همه‌چیز درست است و فقط در محیط تولید مشکل پیش می‌آید.
آنچه از دفتر تجربه ماند
اگر بخواهم کل این مقاله را در سه نکته فشرده کنم: اول، قبل از دست زدن به کد، با View Source و DevTools بررسی کنید که آیا HTML هدر در صفحه هست یا نه؛ این یک بررسی پنج‌ثانیه‌ای، نصف مسیر عیب‌یابی را کوتاه می‌کند. دوم، اگر HTML هست ولی هدر دیده نمی‌شود، مسئله ظاهری است و ریشه‌اش در CSS یا شرط منطقی؛ اگر HTML نیست، مسئله در ساختار قالب یا فراخوانی تمپلیت است. سوم، در نود درصد پرونده‌ها، مقصر در سه لایه اول — فراخوانی get_header، ساختار قالب، یا کش — پنهان است؛ رفتن سراغ لایه‌های پیچیده پیش از بررسی این سه، اتلاف وقت است.
اگر در پروژه‌ای با ناپدید شدن هدر مواجه شده‌اید که در این فهرست نبوده — به‌خصوص در قالب‌های بلوکی، پروژه‌های Headless یا معماری چندسایتی — برایم بنویسید کدام لایه مقصر بود و چطور به جواب رسیدید. تجربه‌های واقعی شما همان چیزی است که این فهرست را برای نفر بعدی دقیق‌تر می‌کند. 🧭
نویسنده در وردپرس کار.