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

یکی از پرونده‌های عجیب روی میز کارم، سایتی بود که بعد از آپدیت قالب، همه‌چیز درست به‌نظر می‌رسید ولی فقط در موبایل، ویجت‌های فوتر ناپدید شده بودند. کارفرما فکر می‌کرد قالب خراب است ولی وقتی دقیق‌تر نگاه کردیم، مسئله در یک تنظیم Customizer بود که در نسخه جدید قالب، پارامتر متفاوتی می‌گرفت. خطای قالب وردپرس، همیشه خطای PHP نیست؛ گاهی خطای تنظیمات، گاهی شکستن CSS، و گاهی نبود یک قابلیت در نسخه جدید است. در این راهنما همان چارچوبی را می‌گویم که در هر پرونده قالب استفاده می‌کنم.

انواع خطای قالب

خطاهای قالب در چهار دسته کلی قرار می‌گیرند:

هر دسته، مسیر تشخیص و درمان متفاوتی دارد. تفکیک این چهار، نیمی از کار است.

خطای قالب، همیشه از قالب نیست؛ گاهی مشکل در تنظیمات، افزونه یا آپدیتی است که رفتار قبلی را تغییر داده.

پیش از هر اقدامی

در تمام پرونده‌های قالب، سه کار پیش از هر تغییر:

1. بکاپ کامل: فایل و دیتابیس. راهنمای بکاپ وردپرس.
2. محیط staging: تغییرات را در محیط تست انجام دهید؛ روش توسعه با محیط لوکال.
3. آماده داشتن قالب پیش‌فرض: قالب Twenty Twenty یا مشابهش نصب باشد تا در صورت خرابی کامل، از طریق FTP فعالش کنید.

این سه، ابزار نجات شما در بحرانی‌ترین لحظات هستند.

پروتکل تشخیص: قالب یا افزونه؟

اولین سوالی که در هر پرونده می‌پرسم: مقصر قالب است یا افزونه؟ سه روش تشخیص:

1. تغییر موقت به قالب پیش‌فرض: اگر خطا رفع شد، مقصر قالب است. اگر نه، مقصر افزونه یا دیتابیس.
2. غیرفعال کردن همه افزونه‌ها: اگر خطا با قالب فعلی و بدون افزونه هم بود، مقصر قطعاً قالب است.
3. مشاهده پیام خطا در debug.log: مسیر فایل مقصر، به قالب یا افزونه اشاره می‌کند.

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

خطای PHP در قالب

خطای PHP در قالب، پرونده‌های اورژانسی هستند. معمولاً بعد از ویرایش فایل‌های قالب رخ می‌دهند. پیام‌های رایج:

• Parse error: syntax error, unexpected ...
• Fatal error: Call to undefined function ...
• Cannot modify header information ...

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

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

خطای Parse در فایل functions.php از رایج‌ترین پرونده‌هاست؛ اگر همین مشکل را دارید، رفع خطای Parse در functions.php مسیر را نشان می‌دهد. برای خطای Fatal در قالب، رفع خطای Fatal در PHP.

شکستن ظاهری و CSS

گاهی سایت بالا می‌آید ولی ظاهرش به‌هم می‌ریزد. سه دلیل رایج:

1. آپدیت قالب: کلاس‌های CSS تغییر کرده‌اند؛ اگر CSS سفارشی دارید، باید با کلاس‌های جدید هماهنگ شود.
2. افزونه کش: نسخه قدیمی CSS در کش مانده. با پاک کردن کش مرورگر و کش افزونه، رفع می‌شود.
3. فونت یا CDN بیرونی: اگر قالب از یک فونت یا منبع بیرونی استفاده می‌کند، و آن منبع در دسترس نیست، ظاهر به‌هم می‌ریزد.

روش سریع تشخیص: در مرورگر، فایل CSS قالب را باز کنید؛ اگر ۴۰۴ برگشت، فایل بارگذاری نشده. اگر سالم بود، کنسول مرورگر را برای خطاهای JS چک کنید. راهنمای تشخیص خطاهای فرانت در پیدا کردن خطاهای JS در کنسول.

شکستن ظاهری، اگر با شکستن ساختار سایت همراه نباشد، معمولاً از جنس CSS است، نه PHP؛ تفکیک این دو، درمان را سریع‌تر می‌کند.

نقش چایلد تم در پیشگیری

۹۰٪ پرونده‌های خطای قالب که به آن‌ها برخورده‌ام، ریشه‌ای ساده داشتند: کاربر کد سفارشی را مستقیم در فایل قالب نوشته بود. با آپدیت قالب، فایل بازنویسی شده و کد سفارشی از بین رفته یا خطا داده است. حلقه مفقوده در این پرونده‌ها، همیشه یک چیز است: چایلد تم.

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

راه‌حل‌های رفع

پس از تشخیص، چهار راه‌حل پیش‌رو دارید:

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

در انتخاب قالب جایگزین، معیارهای پیش از خرید قالب و تشخیص قالب استاندارد را اجرا کنید.

اشتباهات رایج

• ویرایش مستقیم فایل قالب والد: با آپدیت بعدی، همه‌چیز از بین می‌رود.
• حذف قالب بدون بکاپ: اگر مجبور به بازگشت شوید، داده‌های تنظیمات قالب از دست می‌رود.
• نصب قالب اضافه برای رفع مشکل: خود قالب جدید می‌تواند منبع خطا باشد.
• بی‌توجهی به پیام «فایل child theme پیدا نشد»: این پیام معمولاً به missing Template در style.css اشاره دارد.
• فرض خراب بودن قالب وقتی مشکل از کش است: قبل از هر اقدامی، کش مرورگر و کش افزونه را پاک کنید.

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

نگاه راهبردی

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