رصد خطای جاوااسکریپت در وردپرس بدون افزونهٔ سنگین

رصد خطای جاوااسکریپت در وردپرس بدون افزونهٔ سنگین
در این مقاله می‌خوانید
  1. چرا افزونهٔ سنگین راه‌حل نیست
  2. روش درست: قالب فرزند
  3. افزودن اسکریپت رصد
  4. ووکامرس: نکتهٔ اضافه
  5. کدام افزونه‌ها بیشتر تداخل می‌سازند
  6. پیدا کردن مقصر از روی داده
  7. مراقب کش باشید
  8. حریم خصوصی
  9. آزمون نهایی
  10. اسکریپت رصد را از بهینه‌سازی معاف کنید
  11. یک نمونهٔ واقعی: از علامت تا رفع
  12. وقتی خطای مرورگر از سرور می‌آید
  13. پرسش‌های رایج
  14. چرا بعضی خطاها فقط «Script error.» هستند و جزئیاتی ندارند؟
  15. خطاهایی با آدرس chrome-extension:// از کجا می‌آیند؟
  16. خطاهای پیشخوان و ویرایشگر بلوک هم ثبت می‌شوند؟
  17. جمع‌بندی
  18. منابع و مطالعهٔ بیشتر

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

این مقاله راه سبک پوشش دادن آن نیمه است.

چرا افزونهٔ سنگین راه‌حل نیست

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

  • افزونه بیشتر یعنی احتمال تداخل بیشتر — و شما دارید ابزاری اضافه می‌کنید که قرار است مشکل ناشی از تعداد زیاد افزونه را حل کند.
  • سرعت. هر افزونه در هر بارگذاری صفحه اجرا می‌شود.
  • سطح حمله. افزونه‌های وردپرس رایج‌ترین مسیر نفوذ به سایت‌های وردپرسی‌اند.

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

روش درست: قالب فرزند

اگر کد را مستقیم در functions.php قالب اصلی بنویسید، اولین به‌روزرسانی قالب پاکش می‌کند. قالب فرزند بسازید.

یک پوشه در wp-content/themes/ بسازید، مثلاً mytheme-child، و داخلش دو فایل:

style.css

/*
Theme Name: MyTheme Child
Template: mytheme
Version: 1.0.0
*/

مقدار Template باید دقیقاً نام پوشهٔ قالب اصلی باشد.

functions.php

<?php
add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style('parent-style', get_template_directory_uri() . '/style.css');
});

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

افزودن اسکریپت رصد

در functions.php قالب فرزند:

add_action('wp_enqueue_scripts', function () {
    if (is_admin()) return;                    // در پیشخوان لازم نیست

    wp_enqueue_script(
        'error-monitor',
        'https://app.bugmug.ir/bugmug.js',
        array(),
        null,
        false                                  // در head، تا خطاهای زودهنگام هم دیده شوند
    );

    $init = "BugMug.init({ publicKey: 'pk_xxxxxxxx' });";

    // اگر کاربر وارد شده، هویتش را ضمیمه کن تا گزارش‌ها ناشناس نباشند
    if (is_user_logged_in()) {
        $u = wp_get_current_user();
        $init .= sprintf(
            "BugMug.setUser({ id: %s, name: %s, email: %s });",
            wp_json_encode($u->ID),
            wp_json_encode($u->display_name),
            wp_json_encode($u->user_email)
        );
    }

    wp_add_inline_script('error-monitor', $init);
});

سه نکته در این قطعه:

آرگومان آخر false است، یعنی اسکریپت در <head> بارگذاری می‌شود نه در فوتر. برای ابزار رصد خطا این مهم است: اگر در فوتر باشد، خطاهایی که پیش از آن رخ می‌دهند از دست می‌روند.

wp_json_encode برای همهٔ مقادیر، نه چسباندن مستقیم رشته. نام کاربری که آپاستروف داشته باشد، بدون این کار جاوااسکریپت صفحه را می‌شکند — و اگر نام از ورودی کاربر بیاید، مسیر تزریق اسکریپت هم هست.

wp_add_inline_script به‌جای echo. این تضمین می‌کند کد بعد از بارگذاری کتابخانه اجرا شود، نه قبلش.

ووکامرس: نکتهٔ اضافه

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

if (function_exists('is_checkout') && is_checkout()) {
    $init .= "BugMug.addMetadata('stage', 'checkout');";
} elseif (function_exists('is_cart') && is_cart()) {
    $init .= "BugMug.addMetadata('stage', 'cart');";
}

حالا در داشبورد می‌توانید خطاهای صفحهٔ پرداخت را جدا ببینید — که تقریباً همیشه فوری‌ترین دسته‌اند.

کدام افزونه‌ها بیشتر تداخل می‌سازند

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

چند نسخه از jQuery. رایج‌ترین علت. افزونه‌ای نسخهٔ خودش را بارگذاری می‌کند و افزونهٔ دیگری که به نسخهٔ وردپرس تکیه کرده، می‌شکند. نشانه‌اش خطاهایی مثل $ is not a function یا x is not a function روی متدهای jQuery است.

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

صفحه‌سازها. جاوااسکریپت زیادی تزریق می‌کنند و با افزونه‌های فرم و اسلایدر تداخل رایجی دارند.

درگاه‌های پرداخت. کم‌تعدادترین ولی پرهزینه‌ترین، چون دقیقاً در آخرین قدم خرید رخ می‌دهند.

پیدا کردن مقصر از روی داده

وقتی خطاها ثبت می‌شوند، معمولاً لازم نیست حدس بزنید. در stack trace به مسیر فایل نگاه کنید:

at /wp-content/plugins/some-slider/js/slider.min.js:2:1843

نام پوشه در مسیر plugins/، مستقیم می‌گوید کدام افزونه. این تنها تفاوت بین «سایت گاهی خراب می‌شود» و «افزونهٔ فلان روی صفحهٔ تسویه خطا می‌دهد» است.

مراقب کش باشید

افزونه‌های کش صفحات را به‌صورت HTML ثابت ذخیره می‌کنند. اگر کاربر وارد شده باشد ولی صفحهٔ کش‌شده به او داده شود، ممکن است setUser با اطلاعات کاربر دیگری اجرا شود.

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

حریم خصوصی

اگر ویجت گزارش باگ با اسکرین‌شات فعال است، مسئولیت هم می‌آید:

  • فیلدهای رمز عبور به‌صورت خودکار محو می‌شوند.
  • فیلدهای حساس دیگر را خودتان علامت بزنید: <input data-bug-mask> — مثلاً شمارهٔ کارت، کد ملی، شمارهٔ تماس.
  • در صفحهٔ حریم خصوصی سایتتان به این موضوع اشاره کنید.

آزمون نهایی

بعد از نصب، این را در کنسول مرورگر روی سایتتان اجرا کنید:

throw new Error('تست نصب');

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

اسکریپت رصد را از بهینه‌سازی معاف کنید

بیشتر افزونه‌های کش و بهینه‌سازی امروز فقط فایل‌ها را ادغام نمی‌کنند؛ گزینه‌هایی هم دارند که اجرای جاوااسکریپت را عقب می‌اندازند — با defer، یا با «تأخیر در اجرا» تا اولین حرکت ماوس یا لمس صفحه. برای اسکریپت تبلیغات و چت این کار منطقی است. برای اسکریپت رصد خطا، نه.

اگر اسکریپت رصد تا اولین تعامل کاربر اجرا نشود، خطاهای زمان بارگذاری و کاربرانی که بدون تعامل رفته‌اند، ثبت نمی‌شوند — همان دلیلی که اسکریپت را در <head> گذاشتید.

بعد از نصب، این سه چیز را بررسی کنید:

  • در تنظیمات افزونهٔ بهینه‌سازی، آدرس bugmug.js و اسکریپت درون‌خطی بعد از آن را به فهرست استثناهای «ادغام»، «defer» و «تأخیر در اجرا» اضافه کنید.
  • سورس صفحهٔ زنده را در پنجرهٔ ناشناس باز کنید، نه در حالی که وارد پیشخوان هستید، و دنبال bugmug.js بگردید. باید با یک تگ <script> معمولی بیاید، بدون defer و بدون اینکه type آن عوض شده باشد.
  • در وردپرس ۶.۳ به بعد، آرگومان آخر wp_enqueue_script می‌تواند آرایه‌ای با کلید strategy و مقدار defer یا async باشد. برای این اسکریپت آن را تنظیم نکنید.

یک نمونهٔ واقعی: از علامت تا رفع

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

داده. در داشبورد رصد، خطای تازه‌ای با تعداد زیاد ظاهر شده:

ReferenceError: jQuery is not defined
    at https://example.com/product/sample/:412:5

دو سرنخ: مسیر به پوشهٔ plugins/ اشاره نمی‌کند بلکه به خود آدرس صفحه، یعنی خطا از یک اسکریپت درون‌خطی در HTML آمده؛ و زمان شروع خطا با زمان تغییر تنظیمات یکی است.

تشخیص. در سورس صفحهٔ زنده، حوالی خط ۴۱۲ قطعه کد درون‌خطی‌ای هست که یک افزونه برای دکمهٔ سبد خرید چاپ کرده و با jQuery(...) شروع می‌شود. بالاتر، فایل jQuery حالا defer گرفته. ویژگی defer روی اسکریپت درون‌خطی اثری ندارد؛ پس این کد بلافاصله اجرا می‌شود، پیش از آنکه jQuery بارگذاری شده باشد.

رفع. فایل jQuery خود وردپرس (/wp-includes/js/jquery/jquery.min.js) را به استثناهای defer اضافه می‌کنید و کش را پاک می‌کنید.

تأیید. رخدادهای تازهٔ این خطا در داشبورد باید از همان لحظه متوقف شوند. اگر نشدند، احتمالاً نسخهٔ قدیمی صفحه هنوز از جای دیگری به بخشی از کاربران می‌رسد — مثلاً از کش CDN.

وقتی خطای مرورگر از سرور می‌آید

بخشی از خطاهایی که در مرورگر ثبت می‌شوند، ریشه‌شان روی سرور است. فرم‌ها، سبد خرید و فیلترها از طریق admin-ajax.php یا REST API (/wp-json/) با سرور حرف می‌زنند، و وقتی پاسخ خراب باشد، علامتش در جاوااسکریپت ظاهر می‌شود. دو الگوی رایج:

SyntaxError: Unexpected token '<' موقع خواندن JSON. کد انتظار JSON داشته ولی پاسخ با HTML شروع شده: پیام خطای PHP، خروجی ناخواستهٔ یک افزونه، یا صفحهٔ خطای سرور و فایروال. در تب Network پاسخ همان درخواست را باز کنید؛ معمولاً علت در همان چند خط اول است.

کد ۴۰۳ از admin-ajax.php با پاسخ -1، یا از REST API با کد rest_cookie_invalid_nonce. nonce نامعتبر است. وردپرس nonce را داخل HTML صفحه می‌گذارد و عمرش به‌طور پیش‌فرض حداکثر ۲۴ ساعت است؛ صفحه‌ای که بیش از این در کش بماند، nonce کهنه تحویل می‌دهد. نشانه‌اش: بعد از پاک کردن کش، خطا مدتی قطع می‌شود. چاره: صفحه‌های فرم‌دار را از کش معاف کنید یا عمر کششان را کوتاه کنید.

پرسش‌های رایج

چرا بعضی خطاها فقط «Script error.» هستند و جزئیاتی ندارند؟

این خطا از اسکریپتی آمده که از دامنهٔ دیگری بارگذاری شده — CDN، ابزار چت، تبلیغات. مرورگر جزئیات خطای اسکریپت‌های دامنه‌های دیگر را از صفحه پنهان می‌کند. برای اسکریپت شخص ثالث کاری از دستتان برنمی‌آید؛ ولی اگر فایل مال خودتان است و از CDN می‌آید، دو چیز لازم است: ویژگی crossorigin="anonymous" روی تگ اسکریپت، و هدر Access-Control-Allow-Origin در پاسخ CDN — همان سازوکاری که در خطای CORS توضیح داده‌ایم. در وردپرس، ویژگی را با فیلتر script_loader_tag اضافه کنید:

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle === 'my-cdn-script') {
        $tag = str_replace(' src=', ' crossorigin="anonymous" src=', $tag);
    }
    return $tag;
}, 10, 2);

خطاهایی با آدرس chrome-extension:// از کجا می‌آیند؟

از افزونه‌های مرورگر خود کاربر — مترجم، مسدودکنندهٔ تبلیغات، مدیر رمز. اگر در stack trace فقط مسیرهای chrome-extension:// یا moz-extension:// هست، آن خطا را نویز حساب کنید. اگر کاربری گفته دکمه‌ای کار نمی‌کند و چنین خطایی کنارش هست، از او بخواهید در پنجرهٔ ناشناس امتحان کند؛ آنجا افزونه‌ها به‌طور پیش‌فرض خاموش‌اند.

خطاهای پیشخوان و ویرایشگر بلوک هم ثبت می‌شوند؟

با کد بالا نه. قلاب wp_enqueue_scripts فقط برای صفحه‌های سایت اجرا می‌شود و پیشخوان قلاب جداگانهٔ admin_enqueue_scripts دارد. اگر بلوک یا صفحهٔ تنظیمات اختصاصی نوشته‌اید، کد مشابهی را بدون شرط is_admin() به این قلاب هم وصل کنید.

جمع‌بندی

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

و برای این کار به افزونهٔ دیگری نیاز ندارید؛ چند خط در قالب فرزند کافی است.

منابع و مطالعهٔ بیشتر

باگ‌ماگ را رایگان امتحان کنید

خطاهای سایتتان را خودکار ثبت کنید و بگذارید کاربران با یک کلیک باگ گزارش دهند.

شروع رایگان