چگونه خطای قالب را در وردپرس دیباگ کنیم؟

یکی از استرس‌زاترین لحظه‌های کار با وردپرس، وقتی است که سایت مشتری وسط یک کمپین تبلیغاتی، سفید می‌شود. یا بدتر از آن: سایت بالا می‌آید ولی استایل‌ها نمی‌آیند و صفحه، یک آوار متنی بی‌شکل است. من در طول سال‌ها کار با وردپرس، ده‌ها بار در این موقعیت بوده‌ام — ولی تجربه به من آموخته که خطای قالب، اگر با روش منظم دیباگ شود، همیشه در چند دقیقه ریشه‌اش پیدا می‌شود. فقط باید بدانید به چه ترتیبی جلو بروید.

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

خطای قالب، در چه شکل‌هایی ظاهر می‌شود؟

قبل از ورود به پروتکل، بیایید ببینیم «خطای قالب» در عمل به چه شکل‌هایی ظاهر می‌شود. در تجربه‌ی خودم، پنج سناریو تقریباً همه‌ی موارد را پوشش می‌دهند:

نکته‌ی مهم: هر سناریو، پروتکل دیباگ مخصوص خودش را دارد. اگر بدون تشخیص سناریو، مستقیم سراغ تغییر functions.php بروید، احتمال این‌که مشکل بدتر شود، بیشتر از احتمال حلش است. تجربه‌ی من می‌گوید در ۸۰٪ موارد، کاربر بدون تشخیص دقیق، اشتباه‌ترین حدس را می‌زند.

دیباگ کردن، یک عمل جراحی است؛ قبل از هر برشی، باید بدانید به چه چیزی نگاه می‌کنید. هر برش کور، هزینه‌ی بعدی را بالا می‌برد.

قاعده اول: هرگز روی سایت زنده دیباگ نکنید

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

اگر استجینگ ندارید، حداقل دو کار انجام دهید:

1. بکاپ کامل بگیرید: قبل از هر تغییری، از فایل‌ها و دیتابیس نسخه‌ی پشتیبان تهیه کنید. مسیر کامل در چگونه از سایت وردپرسی بکاپ بگیریم.
2. در زمان کم‌ترافیک کار کنید: اگر مجبورید روی سایت زنده تغییر بدهید، در ساعات کم‌ترافیک این کار را انجام دهید تا در صورت خرابی، بازدیدکننده‌ی کمتری تحت تأثیر قرار بگیرد.

یک تذکر جدی از تجربه‌ی خودم: در یک پروژه، بدون بکاپ، وسط یک خطای Parse Error، مجبور شدم کل فایل functions.php را از صفر بازنویسی کنم — چون هیچ نسخه‌ی پشتیبانی نداشتم. آن تجربه، درس گرانی بود که به هر مشتری جدید هم می‌گویم: هیچ‌وقت، هیچ‌وقت، روی چیزی دست نبرید که نسخه‌ی پشتیبان ندارید.

فعال‌سازی WP_DEBUG و لاگ‌گیری

اولین ابزار دیباگ در وردپرس، حالت WP_DEBUG است. این حالت، به وردپرس می‌گوید که همه‌ی خطاها، هشدارها و اعلان‌های PHP را نشان بدهد. برای فعال‌سازی، این چهار خط را در فایل wp-config.php (بالای خط /* That's all, stop editing! */) اضافه کنید:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );

این چهار خط، چهار کار متفاوت می‌کنند:

• WP_DEBUG: فعال‌کردن حالت دیباگ.
• WP_DEBUG_LOG: همه‌ی خطاها در فایل wp-content/debug.log ذخیره شوند.
• WP_DEBUG_DISPLAY: خطاها روی صفحه نمایش داده نشوند (چون در سایت زنده، نمایش خطا امنیتی است).
• SCRIPT_DEBUG: نسخه‌ی توسعه‌ی فایل‌های JS و CSS بار شود، برای دیباگ بهتر.

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

خواندن لاگ: کدام خط را جدی بگیریم؟

بعد از فعال‌سازی، سایت را باز کنید و به فایل wp-content/debug.log نگاه کنید. این فایل، معمولاً یکی از پنج نوع پیام را نشان می‌دهد:

در خطای قالب، به‌طور تجربی سه الگو را در لاگ می‌بینم که بیشترین نشانه‌ی مقصر بودن قالب هستند:

1. مسیر فایل شامل wp-content/themes/[نام‌قالب]: این خطا از قالب می‌آید.
2. خطای در فایل functions.php: مطمئن‌ترین نشانه که خود قالب مشکل دارد.
3. خطای در فایل wp-includes/ ولی با نام تابعی که در قالب تعریف شده: گاهی اوقات قالب، تابعی را با نام مشابه هسته تعریف می‌کند و باعث تضاد می‌شود.

نکته‌ی حرفه‌ای: فقط به «آخرین خط» لاگ نگاه نکنید. بعضی خطاها، ریشه‌ی خطاهای بعدی هستند. به ترتیب زمانی از بالا به پایین بخوانید. یک مثال واقعی: در یکی از پروژه‌ها، خطای نهایی یک پیام Fatal بود، ولی خطای اصلی چند خط بالاتر در یک Warning بود که نشان می‌داد یک متغیر تعریف نشده است. اگر فقط خط آخر را می‌دیدم، اشتباه دیباگ می‌کردم.

گام اول تشخیص: خطا از قالب است یا افزونه؟

قبل از هر اقدام دیگری، باید این سؤال را پاسخ دهید: خطا از قالب است یا از افزونه؟ اگر این تفکیک را نداشته باشید، در دیباگ سرگردان می‌شوید. مسیر ساده:

1. روی محیط لوکال یا استجینگ، همه‌ی افزونه‌ها را غیرفعال کنید.
2. به قالب‌های پیش‌فرض وردپرس (مثل Twenty Twenty-Four) سوئیچ کنید.
3. سایت را باز کنید. اگر مشکل حل شد، قالب مقصر است. اگر مشکل باقی ماند، افزونه مقصر است.
4. اگر خطا از افزونه بود، افزونه‌ها را یکی‌یکی فعال کنید تا مقصر مشخص شود. مسیر کامل در خطای افزونه وردپرس: چگونه آن را پیدا و رفع کنیم.

این تست ساده، ۹۰٪ وقت شما را در دیباگ صرفه‌جویی می‌کند. بدون آن، ممکن است ساعت‌ها وقت صرف بررسی فایل‌های قالب کنید در حالی که مقصر یک افزونه‌ی قدیمی بوده است.

نکته‌ای دیگر: گاهی مشکل، از «ترکیب» یک قالب و یک افزونه به‌وجود می‌آید. یعنی هرکدام به‌تنهایی سالم هستند، ولی وقتی با هم می‌آیند، خطا رخ می‌دهد. در این حالت، باید همه‌ی افزونه‌ها را غیرفعال کنید و یکی‌یکی فعال کنید تا ترکیب مسئله‌ساز مشخص شود.

سناریوی صفحه سفید (White Screen of Death)

«صفحه سفید مرگ» یا White Screen of Death (WSOD)، ترسناک‌ترین سناریو است ولی در واقع یکی از ساده‌ترین‌های دیباگ. چون خطای PHP به‌قدری جدی بوده که اجرای اسکریپت را متوقف کرده. مسیر دیباگ:

1. با FTP یا File Manager به سایت وصل شوید.
2. نام پوشه‌ی قالب فعال را تغییر دهید: این کار، وردپرس را مجبور می‌کند به قالب پیش‌فرض برگردد. اگر سایت بالا آمد، قالب مقصر است.
3. فایل functions.php را در پوشه‌ی قالب بررسی کنید: خطای Parse Error در این فایل، شایع‌ترین ریشه‌ی WSOD است. جزئیات در رفع خطای Parse error در فایل functions.php.
4. در لاگ debug.log به‌دنبال خطای Fatal بگردید: پیام دقیق خطا، مسیر رفع را نشان می‌دهد.

یک نکته‌ی مهم: در بعضی موارد، WSOD از یک افزونه می‌آید، نه قالب. مثلاً یک افزونه‌ی قدیمی که با PHP 8 ناسازگار است. برای همین، تست غیرفعال‌سازی افزونه‌ها را هم انجام دهید. مسیر کامل در خطای سفید صفحه بعد از تغییر قالب و رفع خطای سفید صفحه مرگ در وردپرس آمده است.

سناریوی نبود استایل (Theme Stylesheet Missing)

در این سناریو، سایت بالا می‌آید ولی محتوا بدون استایل دیده می‌شود. یعنی فایل CSS قالب، بارگذاری نمی‌شود. سه ریشه‌ی شایع:

1. عدم وجود فایل style.css در پوشه‌ی قالب: این فایل، شناسنامه‌ی قالب است. اگر حذف شده باشد، قالب ناقص شناخته می‌شود.
2. هدر ناقص یا نادرست در style.css: اگر فیلد Template اشتباه تایپ شده باشد، استایل بار نمی‌شود.
3. عدم بارگذاری صحیح در functions.php: اگر کد wp_enqueue_style اشتباه باشد یا مسیر فایل را نادرست بدهد.

روش تست سریع: در DevTools مرورگر، تب Network را باز کنید و صفحه را ریلود کنید. اگر درخواستی برای style.css وجود ندارد، یعنی قالب آن را بار نمی‌کند. اگر درخواست وجود دارد ولی ۴۰۴ می‌دهد، مسیر فایل اشتباه است. جزئیات در رفع خطای عدم بارگذاری استایل قالب و خطای Missing style.css در قالب وردپرس.

یک نکته‌ی ظریف که در پروژه‌ها دیده‌ام: اگر قالب چایلد تم دارد و فایل style.css در آن هدر ناقص دارد، ممکن است استایل‌های چایلد بار نشوند در حالی که استایل‌های والد بار می‌شوند. مسیر درست چایلد در قالب چایلد وردپرس چیست آمده است.

سناریوی Parse Error در functions.php

خطای Parse Error، نتیجه‌ی یک اشتباه سینتکس در فایل PHP است. مثلاً یک ; فراموش‌شده، یک } جاافتاده، یا یک نقل‌قول باز‌مانده. این خطا معمولاً صفحه‌ی سفید می‌سازد یا پیام مشخصی در بالای صفحه نشان می‌دهد.

مسیر دیباگ:

1. فایل functions.php را باز کنید.
2. به‌دنبال آخرین تغییری بگردید که انجام داده‌اید. ۹۰٪ Parse Errorها بعد از یک ویرایش اخیر رخ می‌دهند.
3. با یک ویرایشگر با قابلیت Syntax Highlighting (مثل VS Code) فایل را باز کنید. این ویرایشگرها، خطاهای سینتکس را معمولاً علامت می‌زنند.
4. اگر نمی‌توانید خطا را پیدا کنید، فایل را از نسخه‌ی پشتیبان بازیابی کنید.

یک تجربه‌ی تکراری که در پروژه‌ها زیاد دیده‌ام: کاربر یک قطعه کد از اینترنت کپی کرده ولی یکی از پرانتزهای بسته را جا انداخته. قطعه‌کدهای آنلاین، اغلب بدون در نظر گرفتن زمینه‌ی فایل شما، فقط کد را می‌دهند. همیشه بعد از کپی، در محیط لوکال تست کنید.

در این نوع خطا، حالت WP_DEBUG بهترین دوست شماست. با فعال‌سازی آن، پیام دقیق Parse Error به شما نشان داده می‌شود که شامل شماره‌ی خط و نوع خطاست. مسیر فنی این ابزار در خطای Parse error در PHP چیست و چگونه رفع می‌شود آمده است.

سناریوی فایل Template Missing

در این سناریو، سایت در بیشتر صفحات کار می‌کند ولی یک نوع صفحه‌ی خاص (مثلاً تک‌نوشته یا یک برگه) خطا می‌دهد. ریشه‌ی معمول، نبود یک فایل قالب است که وردپرس انتظار دارد.

مسیر دیباگ:

1. URL صفحه‌ای که خطا می‌دهد را ببینید. نوع صفحه (تک‌نوشته، برگه، آرشیو) مشخص می‌کند کدام فایل مسئول است.
2. با استفاده از Template Hierarchy، فایل موردانتظار را پیدا کنید. مثلاً برای تک‌نوشته، single.php.
3. پوشه‌ی قالب را چک کنید. اگر فایل موجود نیست، یک قالب دیگر یا نسخه‌ی قبلی را کپی کنید.
4. اگر فایل هست ولی باز نمی‌شود، به خطای PHP داخل آن نگاه کنید. جزئیات در چگونه خطای Template file missing را رفع کنیم.

یک نکته‌ی ظریف: وردپرس در بعضی مواقع، فایل‌های قالب را در مسیرهای مختلف جستجو می‌کند (مثلاً در چایلد تم، بعد در والد). اگر یک فایل در چایلد تم ناقص باشد، ممکن است به‌جای بازگشت به والد، خطا بدهد. مسیر درست ساختار چایلد در ساختار فایل‌های یک قالب استاندارد وردپرس آمده است.

سناریوی ناسازگاری با نسخه وردپرس

این سناریو معمولاً بعد از یک آپدیت وردپرس رخ می‌دهد. قالب، از توابعی استفاده می‌کند که در نسخه‌ی جدید وردپرس حذف یا تغییر کرده‌اند. علائم:

• بعد از آپدیت وردپرس، سایت کند شده یا خطا می‌دهد.
• در لاگ debug.log، پیام‌های Deprecated یا Fatal error دیده می‌شود.
• خطا مربوط به توابع خاصی است که در وردپرس جدید رفتار متفاوتی دارند.

مسیر دیباگ:

1. فایل readme.txt قالب را باز کنید. اگر قالب آپدیت جدید برای وردپرس دارد، اول آن را نصب کنید.
2. در لاگ، نام توابع مسئله‌ساز را جستجو کنید. معمولاً یک یا دو تابع خاص، عامل تمام خطاها هستند.
3. اگر قالب رایگان است و در مخزن رسمی، ممکن است نسخه‌ی جدیدتر داشته باشد. با مخزن بررسی کنید.
4. اگر قالب اختصاصی است، با توسعه‌دهنده‌اش تماس بگیرید. مسیر فنی در رفع خطای ناسازگاری قالب با نسخه وردپرس.

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

تأیید رفع مشکل و پیشگیری از بازگشت

پس از رفع مشکل، سه کار انجام دهید تا مطمئن شوید واقعاً حل شده:

1. لاگ را دوباره چک کنید. با فعال‌بودن WP_DEBUG، سایت را چند صفحه بگردید و مطمئن شوید خطای جدیدی در لاگ نیست.
2. همان مسیر اصلی خطا را اجرا کنید. مثلاً اگر خطا در صفحه‌ی خاصی بود، همان صفحه را باز کنید. اگر در یک فرم، همان فرم را تست کنید.
3. در گوشی موبایل هم چک کنید. بعضی خطاها فقط در یک سایز یا مرورگر خاص رخ می‌دهند. مسیر تست کامل در بهترین روش تست قالب وردپرس قبل از انتشار.

و سپس، مهم‌ترین کار: حالت WP_DEBUG را خاموش کنید. اگر فراموش کنید، هم سایت کند می‌شود، هم در فایل لاگ، حجم زیادی اطلاعات ذخیره می‌شود. یک یادآوری در تقویم بگذارید که یک ساعت بعد، این حالت را خاموش کنید.

نگاه سطح بالا: دیباگ به‌مثابه یک فرآیند سیستماتیک

برای توسعه‌دهنده‌ای که سال‌ها روی سیستم‌های پیچیده کار کرده، «دیباگ خطای قالب» در نگاه اول یک فعالیت موردی به نظر می‌رسد. اما در چارچوب‌های مهندسی جدی، دیباگ یک فرآیند سیستماتیک است که فقط با رعایت ترتیب و روش، به نتیجه‌ی قابل‌اعتماد می‌رسد. این فرآیند، چهار مرحله دارد که در هر خطای فنی به‌کار می‌آید:

• مرحله‌ی ۱ — مشاهده (Observation): قبل از هر تغییری، دقیقاً ببینید چه اتفاقی افتاده. کدام صفحه، کدام مرورگر، کدام لحظه. یک دیباگ خوب، هشتاد درصد وقت خود را صرف مشاهده می‌کند و بیست درصد صرف تغییر.
• مرحله‌ی ۲ — فرضیه‌سازی (Hypothesis): بر اساس مشاهدات، یک یا دو فرضیه‌ی محتمل بسازید. فرضیه‌ی بدون مشاهده، فقط حدس است.
• مرحله‌ی ۳ — آزمون کنترل‌شده (Isolation): هر فرضیه را با یک آزمون جداگانه بسنجید. یک تغییر در یک زمان. اگر هم‌زمان سه چیز را تغییر دهید، نه می‌فهمید کدام مؤثر بوده، نه می‌توانید مطمئن باشید خطا برنگشته.
• مرحله‌ی ۴ — تأیید (Verification): بعد از یافتن مقصر و رفع آن، حتماً تأیید کنید که مشکل واقعاً رفع شده. تأیید، بخشی جداگانه از دیباگ است، نه بخشی از رفع. اگر این مرحله را حذف کنید، ممکن است خطا در شرایط خاصی برگردد و شما هیچ‌وقت متوجه نشوید.

یک نکته‌ی مهم در این چارچوب: دیباگ کردن، همیشه به «ریشه» نمی‌رسد. گاهی وقت‌ها، خطا ناشی از ترکیب چند عامل است که هیچ‌کدام به‌تنهایی مشکل‌ساز نیستند. در این حالت، به‌جای دنبال‌کردن یک علت واحد، باید دنبال «شرایطی که خطا را می‌سازند» گشت. این تفکر، تفاوت بین یک دیباگر معمولی و یک مهندس باتجربه است. در نهایت، مهارت دیباگ، بیشتر از آن‌که به دانش فنی وابسته باشد، به انضباط فکری وابسته است: رعایت ترتیب، حذف حدس‌های بی‌پایه، و پذیرش این حقیقت که هر گام اشتباه، هزینه‌ی گام بعدی را بالا می‌برد.

برای درک عمیق‌تر این تفکر در پروژه‌های وردپرسی، اشتباهات رایج در توسعه قالب و افزونه وردپرس و آموزش استفاده از هوک‌های وردپرس برای توسعه‌دهندگان را در کنار این بحث بخوانید.

آنچه از این راهنما باید با خود ببرید

خلاصه‌ی پروتکل دیباگ خطای قالب در یک جمله: اول عدد بگیر، بعد فرضیه بساز، بعد یک تغییر در یک زمان، و در آخر تأیید کن. اگر این چهار مرحله را رعایت کنید، هیچ خطای قالبی نیست که در بیش از نیم‌ساعت قابل‌حل نباشد.

قدم عملی امشب‌تان: در سایت خودتان، حالت WP_DEBUG را روی محیط لوکال فعال کنید و برای پنج دقیقه، پنج صفحه‌ی مختلف را بگردید. حتی اگر خطایی نداشته باشید، حداقل با ابزار لاگ‌گیری آشنا می‌شوید و روزی که به آن نیاز دارید، آماده خواهید بود.

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