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

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

خطاهای افزونه در چه شکل‌هایی ظاهر می‌شوند؟

پیش از هر بررسی، باید بدانید کدام علامت را می‌بینید؛ چون هر علامت، مسیر تشخیص متفاوتی دارد:

علامت اول و دوم معمولاً اورژانسی‌اند؛ سوم و چهارم بیشتر آزاردهنده. اول باید نوع خطا را بفهمید تا با روش درست سراغش بروید.

هر خطای افزونه، یک جنس دارد؛ اگر جنس را اشتباه تشخیص دهید، درمان هم اشتباه می‌شود.

پیش از هر اقدامی: بکاپ و محیط تست

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

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

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

پروتکل غیرفعال‌سازی مرحله‌ای

سریع‌ترین روش پیدا کردن افزونه مقصر، غیرفعال کردن دسته‌ای است، نه تکی. وقتی افزونه‌های زیادی دارید، غیرفعال کردن یکی‌یکی طول می‌کشد. روش من:

1. همه افزونه‌ها را غیرفعال کنید.
2. نصف اول را فعال کنید و ببینید خطا برمی‌گردد یا نه.
3. اگر خطا برگشت، مقصر در همان نصف است؛ نصف دیگر را کنار بگذارید.
4. در نصف مقصر، دوباره نصف کنید تا به یک افزونه برسید.

این روش باینری، تعداد تست‌ها را از N به log N کاهش می‌دهد. با ۳۲ افزونه، به جای ۳۲ تست، فقط ۵ تست لازم است.

اگر پیشخوان سایت باز نمی‌شود و نمی‌توانید افزونه‌ها را غیرفعال کنید، از طریق FTP وارد پوشه wp-content/plugins شوید و نام همه پوشه‌ها را موقتاً تغییر دهید. سپس از پیشخوان، یکی‌یکی فعال کنید.

# غیرفعال کردن همه افزونه‌ها از طریق WP-CLI
wp plugin deactivate --all

# فعال کردن یک افزونه
wp plugin activate plugin-name

تعارض بین دو افزونه

در تجربه من، حدود ۳۰٪ پرونده‌های خطای افزونه، تعارض بین دو افزونه است، نه خرابی خود یک افزونه. الگوهای رایج تعارض:

• دو افزونه سئو همزمان فعال: هر دو sitemap و متا تولید می‌کنند و به هم ضربه می‌زنند.
• دو افزونه کش همزمان: هر دو کش صفحه می‌سازند و invalidation را نقض می‌کنند.
• افزونه فرم و افزونه امنیتی: یکی به کوکی و دیگری به سشن دست می‌زند.
• دو افزونه که یک تابع مشترک را تعریف می‌کنند: خطای Cannot redeclare function.
• افزونه بکاپ و افزونه دیتابیس: هر دو به جدول‌های مشترک دست می‌زنند.

در این حالت، مقصر یک افزونه نیست؛ تعارض است. راه حل: یا یکی از دو را حذف کنید، یا با فیلترها و هوک، رفتارشان را سازگار کنید. راهنمای تفصیلی در رفع تعارض افزونه‌ها.

در نیمی از پرونده‌های تعارض، کاربر با نصب افزونه جدیدی سعی می‌کند مشکل را حل کند؛ نتیجه، سه‌برابر شدن تعارض است.

خواندن لاگ و پیدا کردن افزونه مقصر

در وردپرس، برای دیدن خطای واقعی PHP باید حالت دیباگ را فعال کنید:

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

این سه خط را در wp-config.php اضافه کنید. از این لحظه، خطاها در فایل wp-content/debug.log ثبت می‌شوند. در این فایل، معمولاً مسیر کامل فایل مقصر ذکر شده است:

PHP Fatal error: Uncaught Error: Call to undefined function my_plugin_func() in /wp-content/plugins/my-plugin/inc/file.php on line 42

مسیر /wp-content/plugins/my-plugin/ مستقیماً به افزونه مقصر اشاره می‌کند. اگر چند خطا در لاگ هست، همیشه خط آخر را ببینید؛ خطاهای بعدی معمولاً نتیجه خطای اول‌اند.

اگر خطا با کندی هم همراه است، لایه دیگری مطرح می‌شود که در تأثیر افزونه‌ها بر سرعت توضیح داده‌ام.

با WP-CLI: سریع‌ترین روش

اگر به SSH دسترسی دارید، WP-CLI سریع‌ترین راه است. بدون نیاز به پیشخوان، می‌توانید افزونه‌ها را فهرست، فعال و غیرفعال کنید:

wp plugin list
wp plugin deactivate plugin-name
wp plugin update --all
wp plugin verify-checksums --all

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

راه‌حل‌های رفع: از جایگزینی تا حذف

پس از پیدا کردن افزونه مقصر، چهار مسیر پیش‌رو دارید:

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

قبل از حذف افزونه، به دو نکته توجه کنید: آیا داده‌ای در دیتابیس دارد که با حذف از دست می‌رود؟ آیا فایل‌هایی در wp-content/uploads دارد؟ پست حذف افزونه خراب بدون از دست دادن تنظیمات این مسیر را باز کرده است.

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

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

در انتخاب افزونه جایگزین هم به همان اصول دانلود افزونه مطمئن پایبند باشید.

جمع‌بندی راهبردی

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