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

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

وردپرس (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) انجام می‌شود.

1. وارد محیط مدیریت فایل شوید.
2. فایل wp-config.php را که در روت اصلی سایت قرار دارد، پیدا کنید.
3. این فایل را برای ویرایش باز کنید.
4. درست قبل از خط /* 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 مواجه شده و به پیشخوان دسترسی ندارید، باید این فرآیند را به صورت دستی از طریق هاست انجام دهید:

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

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

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

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

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

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

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

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

1. ویرایش wp-config.php: خط زیر را اضافه یا ویرایش کنید. (۲۵۶M مقدار استانداردی است):

   define( 'WP_MEMORY_LIMIT', '256M' );

2. ویرایش php.ini: اگر به فایل php.ini دسترسی دارید (که معمولاً در هاست‌های اشتراکی امکان‌پذیر نیست)، مقدار memory_limit را افزایش دهید:

   memory_limit = 256M

3. تماس با پشتیبانی هاست: اگر روش‌های بالا کار نکرد، محدودیت‌های سرور میزبان شما ممکن است اجازه تغییر ندهد. در این صورت، با تیم پشتیبانی هاست خود تماس بگیرید و درخواست افزایش 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 );

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

منابع

• معایب استفاده از هاست (سرور ایرانی) برای وردپرس؛ نگاهی عمیق‌تر
• اصول بهینه سازی سرعت وب سایت در 2025: راهنمای جامع برای موفقیت آنلاین
• خطایابی وردپرس
• افزونه وردپرس

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

• 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 یک ثابت در فایل wp-config.php است که حالت اشکال‌زدایی وردپرس را فعال می‌کند. با فعال‌سازی آن، وردپرس تمام خطاهای PHP، اخطارها و اطلاعیه‌ها را نمایش می‌دهد یا در فایل debug.log ثبت می‌کند، که این امر برای رفع خطا وردپرس و شناسایی منبع مشکل ضروری است.

چگونه بفهمم که خطا از افزونه است یا از قالب؟

بهترین روش این است که ابتدا نام پوشه افزونه‌ها (plugins) را به صورت موقت تغییر دهید. اگر سایت درست شد، مشکل از یک افزونه است. سپس نام پوشه را به حالت اول برگردانید و افزونه‌ها را یکی یکی فعال کنید تا افزونه مقصر شناسایی شود. اگر مشکل حل نشد، همین فرآیند را برای پوشه قالب فعلی (themes) انجام دهید.

خطای Memory Limit Exhausted به چه معناست و چگونه آن را رفع کنم؟

این خطا به این معنی است که یک اسکریپت تلاش کرده است بیش از حد مجاز حافظه RAM اختصاص داده شده به PHP را مصرف کند. برای رفع آن، باید محدودیت حافظه (Memory Limit) را با افزودن define('WP_MEMORY_LIMIT', '256M'); به فایل wp-config.php افزایش دهید.

فایل debug.log کجا قرار دارد و چگونه می‌توانم آن را بررسی کنم؟

فایل debug.log به طور پیش‌فرض در پوشه wp-content در ریشه سایت شما قرار می‌گیرد، به شرطی که ثابت WP_DEBUG_LOG را روی true تنظیم کرده باشید. شما می‌توانید این فایل را از طریق File Manager هاست یا FTP دانلود و با یک ویرایشگر متنی بررسی کنید.

اگر به پیشخوان وردپرس دسترسی نداشته باشم، چگونه می‌توانم دیباگ را شروع کنم؟

در صورت عدم دسترسی به پیشخوان، باید تمام مراحل دیباگ وردپرس را از طریق دسترسی مستقیم به فایل‌های سرور (با استفاده از FTP یا File Manager) انجام دهید. ابتدا با ویرایش wp-config.php دیباگ را فعال کنید و سپس با تغییر نام پوشه‌های plugins و themes، منبع خطا را جدا کنید.

ناسازگاری PHP چه تأثیری بر عملکرد سایت دارد؟

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

چگونه خطای “This site is experiencing technical difficulties” را رفع کنم؟

این پیام عمومی به این معناست که یک خطای مهلک رخ داده است. در این حالت، وردپرس یک ایمیل حاوی جزئیات خطا برای مدیر سایت ارسال می‌کند. با فعال‌سازی WP_DEBUG_LOG، اطلاعات دقیق خطا در فایل debug.log ثبت می‌شود که می‌توانید از آن برای یافتن فایل مقصر استفاده کنید.

آیا پس از اتمام دیباگ، باید WP_DEBUG را غیرفعال کنم؟

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