مراحل دیباگ وردپرس (از صفر تا ۱۰۰) و رفع انواع خطاهای رایج

چرا مراحل دیباگ وردپرس حیاتی است؟

وردپرس (WordPress) با سهمی بیش از ۴۰ درصدی از کل وب‌سایت‌های جهان، قدرتمندترین و محبوب‌ترین سیستم مدیریت محتوا (CMS) محسوب می‌شود. با این حال، ماهیت متن‌باز بودن، به‌روزرسانی‌های مداوم و استفاده از افزونه‌ها و قالب‌های متعدد، آن را مستعد بروز خطا می‌کند. سایت‌های وردپرسی ممکن است با مشکلاتی از قبیل صفحه سفید مرگ (White Screen of Death)، خطاهای دیتابیس، یا کندی شدید مواجه شوند. در چنین شرایطی، دانستن مراحل دیباگ وردپرس یک مهارت حیاتی برای هر مدیر سایت یا توسعه‌دهنده به شمار می‌رود. دیباگ وردپرس تنها به معنای یافتن خطا نیست، بلکه فرآیندی جامع برای تضمین پایداری، امنیت و بهبود عملکرد سایت است. در این مقاله، ما تمام مراحل دیباگ وردپرس، از صفر تا ۱۰۰ مراحل، را به صورت گام به گام و کاربردی بررسی خواهیم کرد تا بتوانید به طور موثر هر نوع رفع خطا وردپرس را انجام دهید.

اهمیت دیباگینگ در حفظ سلامت و سئو سایت

خطاهای پنهان یا آشکار وردپرس می‌توانند تأثیر مخربی بر تجربه کاربری (UX) و در نتیجه رتبه‌بندی سئوی (SEO) سایت شما بگذارند. برای مثال، خطاهای PHP می‌توانند باعث شوند کراولرهای گوگل نتوانند محتوای سایت را به درستی ایندکس کنند یا زمان بارگذاری صفحه به شدت افزایش یابد که این خود ناقض اصول بهینه‌سازی سرعت وب‌سایت است. بنابراین، درک اصول خطایابی وردپرس بخش جدایی‌ناپذیر از مدیریت موفق یک وب‌سایت حرفه‌ای است.

مرحله اول: فعال‌سازی سیستم جامع دیباگ وردپرس (WP_DEBUG)

اولین و مهم‌ترین گام در مراحل دیباگ وردپرس، فعال کردن قابلیت داخلی اشکال‌زدایی وردپرس از طریق تعریف ثابت‌های مشخص در فایل wp-config.php است. این فایل مغز متفکر سایت وردپرسی شماست و در ریشه اصلی نصب وردپرس (معمولاً در public_html) قرار دارد.

نحوه دسترسی به فایل wp-config.php (FTP یا File Manager)

برای ویرایش این فایل، شما به دسترسی به سرور میزبان خود نیاز دارید. این کار معمولاً از طریق یک کلاینت FTP (مانند FileZilla) یا از طریق File Manager در پنل‌های مدیریتی هاست (مانند cPanel یا DirectAdmin) انجام می‌شود.

وارد محیط مدیریت فایل شوید.
فایل wp-config.php را که در روت اصلی سایت قرار دارد، پیدا کنید.
این فایل را برای ویرایش باز کنید.
درست قبل از خط /* That's all, stop editing! Happy blogging. */، کد زیر را اضافه کنید یا اگر از قبل وجود داشت، مقدار false آن را به true تغییر دهید:

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

توضیح ثابت‌های کلیدی WP_DEBUG

WP_DEBUG (ضروری): با تنظیم این مقدار روی true، سیستم کلی دیباگ فعال می‌شود. این ثابت به وردپرس دستور می‌دهد که خطاهای PHP و اخطارهای احتمالی را نمایش دهد.
WP_DEBUG_LOG (لازم): این ثابت به وردپرس دستور می‌دهد تا تمامی خطاها، اخطارها و اطلاعیه‌هایی که در حین اجرای کد رخ می‌دهد را در یک فایل متنی به نام debug.log ذخیره کند. فعال کردن این قابلیت بسیار مهم است، زیرا به شما اجازه می‌دهد خطاها را بدون نمایش دادن آن‌ها به کاربران سایت، بررسی کنید.
WP_DEBUG_DISPLAY (توصیه شده: false): این ثابت مشخص می‌کند که آیا خطاها باید مستقیماً در صفحات وب نمایش داده شوند یا خیر. به شدت توصیه می‌شود در محیط عملیاتی (Production) این مقدار را روی false نگه دارید تا اطلاعات حساس یا کدهای به هم ریخته به بازدیدکنندگان عادی نشان داده نشود.

تنظیمات پیشرفته دیباگ برای توسعه‌دهندگان

اگر یک توسعه‌دهنده هستید یا می‌خواهید دیباگ عمیق‌تری انجام دهید، می‌توانید ثابت‌های زیر را نیز به wp-config.php اضافه کنید:

define( 'SCRIPT_DEBUG', true ); // از نسخه های مینیفای شده CSS/JS استفاده نمی‌کند.
define( 'SAVEQUERIES', true ); // کوئری های دیتابیس را ذخیره می‌کند (فقط برای تست).

مرحله دوم: تجزیه و تحلیل گزارش خطاها در فایل debug.log

پس از فعال‌سازی WP_DEBUG_LOG، وردپرس یک فایل جدید به نام debug.log در پوشه wp-content ایجاد می‌کند. این فایل مهم‌ترین ابزار شما برای رفع خطا وردپرس است.

نحوه خواندن فایل debug.log

هر خط در این فایل نشان‌دهنده یک رویداد خطا است و شامل اطلاعات حیاتی زیر است:

نوع خطا: (مانند Fatal Error, Warning, Notice). خطاهای Fatal (مهلک) از همه مهم‌ترند، زیرا باعث توقف کامل اجرای اسکریپت و نمایش خطای صفحه سفید می‌شوند.
مسیر فایل: مسیر دقیق فایلی که خطا در آن رخ داده (مثلاً /wp-content/plugins/bad-plugin/file.php). این بخش مستقیماً مقصر اصلی (معمولاً یک افزونه وردپرس یا یک فایل در هسته وردپرس) را مشخص می‌کند.
شماره خط: شماره دقیق خط کد که باعث تولید خطا شده است.

مرحله سوم: جداسازی عامل خطا (تست افزونه و قالب)

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

آیا خطای صفحه سفید مرگ (White Screen of Death) مشاهده می‌شود؟

اگر سایت شما با خطای WSOD مواجه شده و به پیشخوان دسترسی ندارید، باید این فرآیند را به صورت دستی از طریق هاست انجام دهید:

توقف افزونه‌ها: به پوشه wp-content در هاست خود بروید و نام پوشه plugins را به plugins-off یا هر نام دیگری تغییر دهید. این کار باعث می‌شود وردپرس نتواند هیچ افزونه‌ای را بارگذاری کند.
آزمایش سایت: اگر سایت شما دوباره بالا آمد، مشخص می‌شود که مشکل از یکی از افزونه‌ها بوده است. نام پوشه را به plugins برگردانید و برای شناسایی مقصر، به مرحله بعد بروید.
توقف قالب: اگر سایت با غیرفعال کردن افزونه‌ها هنوز خطا می‌دهد، نام پوشه قالب فعال فعلی خود (که در wp-content/themes قرار دارد) را تغییر دهید. با این کار، وردپرس به طور خودکار به یک قالب پیش‌فرض (مانند Twenty Twenty-Four) سوئیچ می‌کند. اگر سایت درست شد، مشکل از قالب شماست.

شناسایی افزونه یا قالب مخرب (فعال‌سازی مرحله‌ای)

اگر با تغییر نام پوشه افزونه‌ها، سایت شما بازگشت (مرحله ۲)، این مراحل را دنبال کنید:

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

مرحله چهارم: بررسی و افزایش محدودیت حافظه PHP (Memory Limit)

یکی از رایج‌ترین خطاهایی که در debug.log مشاهده می‌شود، خطای «Allowed memory size of X bytes exhausted» است. این خطا زمانی رخ می‌دهد که یک اسکریپت (معمولاً افزونه یا قالب سنگین) تلاش می‌کند بیش از حد مجاز PHP از حافظه سرور استفاده کند.

نحوه افزایش محدودیت حافظه

این مورد به شدت به محیط هاست وردپرس شما بستگی دارد. با این حال، سه روش اصلی وجود دارد:

ویرایش wp-config.php: خط زیر را اضافه یا ویرایش کنید. (۲۵۶M مقدار استانداردی است):
```
define( 'WP_MEMORY_LIMIT', '256M' );
```
ویرایش php.ini: اگر به فایل php.ini دسترسی دارید (که معمولاً در هاست‌های اشتراکی امکان‌پذیر نیست)، مقدار memory_limit را افزایش دهید:
```
memory_limit = 256M
```
تماس با پشتیبانی هاست: اگر روش‌های بالا کار نکرد، محدودیت‌های سرور میزبان شما ممکن است اجازه تغییر ندهد. در این صورت، با تیم پشتیبانی هاست خود تماس بگیرید و درخواست افزایش Memory Limit را مطرح کنید.

مرحله پنجم: به‌روزرسانی هسته وردپرس و بررسی ناسازگاری PHP

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

بروزرسانی دستی فایل‌های هسته

اگر به پیشخوان وردپرس دسترسی ندارید، باید وردپرس را به صورت دستی به‌روزرسانی کنید:

آخرین نسخه وردپرس را از وب‌سایت رسمی دانلود کنید.
فایل‌های wp-content و wp-config.php را در سرور خود نگه دارید.
تمامی فایل‌های اصلی وردپرس (مانند پوشه‌های wp-includes و wp-admin و سایر فایل‌های ریشه) را با نسخه‌های جدید و سالم جایگزین کنید.

ناسازگاری نسخه‌ی PHP

نسخه PHP که هاست شما استفاده می‌کند، تأثیر مستقیمی بر سلامت وردپرس دارد. وردپرس نسخه‌های قدیمی‌تر PHP (مانند PHP 7.4 و پایین‌تر) را منسوخ شده و ناامن می‌داند. برای رفع خطا وردپرس، مطمئن شوید که سرور شما از PHP 8.1 یا بالاتر استفاده می‌کند.

بررسی در Site Health: در پیشخوان وردپرس، بخش «ابزارها» > «سلامت سایت»، بخش «وضعیت» ناسازگاری‌های PHP را نشان می‌دهد.
تغییر نسخه PHP: از طریق پنل مدیریتی هاست (cPanel/DirectAdmin) می‌توانید نسخه PHP سایت خود را به آخرین نسخه سازگار با وردپرس تغییر دهید.

مرحله ششم: عیب‌یابی خطاهای رایج Site Health (REST API و Loopback)

بخش سلامت سایت (Site Health) در وردپرس به شما کمک می‌کند تا مشکلات زیرساختی را که ممکن است باعث اختلال در عملکرد پلاگین‌ها یا ویرایشگر گوتنبرگ شوند، شناسایی کنید. دو خطای رایج عبارتند از:

خطای REST API

این خطا زمانی رخ می‌دهد که وردپرس نتواند با خودش ارتباط برقرار کند. REST API پایه و اساس ویرایشگر گوتنبرگ و بسیاری از ویژگی‌های مهم افزونه‌های مدرن وردپرس است.

راهکارهای رفع خطای REST API:

بررسی فایروال: اگر از یک فایروال ابری (مانند Cloudflare) یا فایروال سرور استفاده می‌کنید، مطمئن شوید که درخواست‌های Loopback (ارتباط داخلی سایت با خودش) مسدود نشده باشند.
بررسی افزونه‌های امنیتی: افزونه‌های امنیتی سخت‌گیر می‌توانند REST API را مسدود کنند. آن‌ها را موقتاً غیرفعال کنید.

خطای Loopback (درخواست بازگشتی)

این خطا نیز به ناتوانی وردپرس در اجرای وظایف زمان‌بندی شده داخلی (مثل به‌روزرسانی‌ها یا زمان‌بندی انتشار پست‌ها) اشاره دارد. اگر با خطای Loopback مواجه هستید، ممکن است به دلیل مشکلات DNS، محدودیت‌های سرور، یا تداخلات شدید PHP باشد.

راهکارها:

بررسی DNS: اطمینان حاصل کنید که DNS سایت شما به درستی تنظیم شده باشد و سرور بتواند نام دامنه خود را به درستی حل کند.
بررسی لاگ سرور: از پشتیبانی هاست بخواهید لاگ‌های خطای سرور را بررسی کنند تا ببینند آیا درخواست‌های Loopback به دلیل timeout یا محدودیت‌های سخت‌افزاری مسدود می‌شوند یا خیر.

مرحله هفتم: تنظیم مجدد آدرس‌های URL و لینک‌های ثابت (Permalink)

گاهی اوقات، پس از انتقال سایت (Migration) یا تغییر پروتکل (از HTTP به HTTPS)، تنظیمات آدرس‌های سایت در پایگاه داده خراب می‌شود، که منجر به خطاهای 404 یا هدایت‌های اشتباه می‌شود.

بررسی WP_HOME و WP_SITEURL

مطمئن شوید که ثابت‌های زیر در wp-config.php یا در تنظیمات عمومی وردپرس به درستی تنظیم شده باشند:

define('WP_HOME','https://yourdomain.com');
define('WP_SITEURL','https://yourdomain.com');

بازسازی لینک‌های ثابت (Permalink)

حتی اگر به پیشخوان دسترسی ندارید و با خطای 404 در صفحات داخلی مواجه‌اید، می‌توانید با حذف و بازسازی فایل .htaccess این مشکل را حل کنید:

از طریق File Manager به فایل .htaccess در ریشه سایت دسترسی پیدا کنید و آن را حذف کنید (حتماً یک نسخه پشتیبان نگه دارید).
اگر به پیشخوان دسترسی پیدا کردید، به «تنظیمات» > «پیوندهای یکتا» بروید و بدون هیچ تغییری، فقط روی «ذخیره تغییرات» کلیک کنید. وردپرس به صورت خودکار یک فایل .htaccess جدید و سالم ایجاد می‌کند.

مرحله هشتم: دیباگ دیتابیس (Database Debugging)

اگر خطاهای شما به جدول‌ها یا کوئری‌های دیتابیس اشاره دارند (مانند خطای «Error Establishing a Database Connection»)، باید اتصال وردپرس به دیتابیس را بررسی کنید.

بررسی اطلاعات اتصال به دیتابیس

اطمینان حاصل کنید که اطلاعات زیر در wp-config.php صحیح باشند:

DB_NAME (نام دیتابیس)
DB_USER (نام کاربری دیتابیس)
DB_PASSWORD (رمز عبور دیتابیس)
DB_HOST (آدرس میزبان دیتابیس، معمولاً localhost)

اگر این اطلاعات صحیح بودند، ممکن است نیاز به تعمیر دیتابیس از طریق phpMyAdmin یا فعال‌سازی ثابت تعمیر دیتابیس در wp-config.php داشته باشید:

define('WP_ALLOW_REPAIR', true);

پس از افزودن این خط، به آدرس http://yourdomain.com/wp-admin/maint/repair.php بروید و فرآیند تعمیر را انجام دهید. فراموش نکنید پس از اتمام کار، این ثابت را حذف کنید.

نتیجه‌گیری: پایدارسازی سایت پس از اتمام دیباگ

پس از اینکه موفق شدید مراحل دیباگ وردپرس را با موفقیت پشت سر گذاشته و رفع خطا وردپرس را انجام دهید، بسیار مهم است که محیط دیباگ را به حالت عادی برگردانید. نمایش اطلاعات خطا به کاربران یا ذخیره کردن لاگ‌های دیتابیس در طولانی مدت، می‌تواند به امنیت سایت آسیب برساند یا فضای ذخیره‌سازی را هدر دهد. بنابراین، تمامی ثابت‌های فعال شده در wp-config.php را به حالت false برگردانید:

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

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

منابع

مراجع برون‌سازمانی

WordPress Codex Debugging: راهنمای رسمی توسعه‌دهندگان برای استفاده از ابزارهای داخلی اشکال‌زدایی وردپرس و تفسیر انواع خطاها.
PHP Error Reporting Levels: مرجعی برای درک تفاوت بین خطاهای Notice، Warning و Fatal و نحوه مدیریت هر یک در محیط PHP.
WPBeginner Guide to White Screen of Death: راهنمای گام به گام رفع رایج‌ترین خطای وردپرس که مانع دسترسی به سایت و پنل مدیریت می‌شود.
Site Health Status Documentation: توضیحات جامع در مورد ابزار سلامت سایت وردپرس و نحوه رفع مشکلات حیاتی مانند REST API و Loopback.

Sources for reference only, all content is original.

سوالات متداول

WP_DEBUG چیست و چرا فعالش کنیم؟
WP_DEBUG حالت خطایابی WordPress است؛ خطاهای PHP را نمایش یا داخل debug.log ذخیره می‌کند تا سریع منبع مشکل را پیدا کنید.

چطور بفهمم مشکل از افزونه است یا قالب؟
پوشه plugins را موقت تغییر نام بده؛ اگر درست شد، مشکل از افزونه است. در غیر این صورت همین کار را برای پوشه قالب (themes) انجام بده.

Memory Limit Exhausted یعنی چی؟
یعنی اسکریپت بیش از حافظه مجاز مصرف کرده. با افزایش WP_MEMORY_LIMIT (مثلاً 256M) در wp-config.php حل می‌شود.

فایل debug.log کجاست؟
داخل پوشه wp-content (به شرط فعال بودن WP_DEBUG_LOG).

اگر به پیشخوان دسترسی نداشته باشم چی؟
از FTP یا File Manager وارد سرور شو، WP_DEBUG را فعال کن و پوشه‌های افزونه/قالب را تغییر نام بده.

ناسازگاری PHP چه تأثیری دارد؟
نسخه قدیمی PHP باعث خطا، کندی و ریسک امنیتی می‌شود؛ نسخه‌های جدید (مثل 8.1+) پایدارترند.

خطای “This site is experiencing technical difficulties” یعنی چی؟
یک خطای مهلک رخ داده؛ جزئیات در ایمیل مدیر سایت یا debug.log پیدا می‌شود.

بعد از دیباگ، WP_DEBUG را خاموش کنم؟
حتماً بله؛ برای جلوگیری از نمایش اطلاعات حساس و مصرف بیهوده منابع سرور.