window.onerror و unhandledrejection: تور ایمنی سراسری سایت

window.onerror و unhandledrejection: تور ایمنی سراسری سایت
در این مقاله می‌خوانید
  1. دو رویداد، نه یکی
  2. window.onerror یا addEventListener؟
  3. یک پیاده‌سازی کامل
  4. نکاتی که در پیاده‌سازی ساده جا می‌مانند
  5. خطای Script error.
  6. خطای بارگذاری منابع
  7. حلقهٔ بی‌نهایت
  8. سیل رخداد
  9. خطاهایی که مال شما نیستند
  10. چه چیزهایی به این شنونده‌ها نمی‌رسد
  11. چه چیزی را همراه خطا بفرستیم
  12. محدودسازی نرخ، جدی‌تر از آنچه فکر می‌کنید
  13. چطور تستش کنیم
  14. یک نمونهٔ واقعی: وقتی رفع Script error. سایت را از کار می‌اندازد
  15. خطا را کجا بفرستیم؟
  16. مکمل ضروری: صدای کاربر
  17. پرسش‌های رایج
  18. چرا e.error گاهی خالی است یا stack ندارد؟
  19. در Node.js معادل این دو رویداد چیست؟
  20. آیا خطای نحوی (SyntaxError) هم گرفته می‌شود؟
  21. جمع‌بندی
  22. منابع و مطالعهٔ بیشتر

هر چقدر هم دقیق باشید، خطاهایی هستند که پیش‌بینی نکرده‌اید. تور ایمنی سراسری برای همان‌هاست: مکانیزمی که هر خطایی را که از تمام try/catchها رد شده و به بالاترین سطح رسیده، می‌گیرد و ثبت می‌کند.

این مقاله راهنمای ساختن آن است — و توضیح اینکه چرا نسخهٔ ساده‌اش معمولاً کافی نیست.

دو رویداد، نه یکی

مهم‌ترین نکته‌ای که بیشتر پیاده‌سازی‌های دست‌ساز از قلم می‌اندازند: خطاهای همگام و Promiseهای رد شده دو رویداد جدا دارند.

// خطاهای معمولی
window.addEventListener('error', function (e) { /* ... */ });

// Promise هایی که rejected شدند و catch نداشتند
window.addEventListener('unhandledrejection', function (e) { /* ... */ });

اگر فقط اولی را بگذارید، در کد امروزی که بیشتر منطقش async است، بخش بزرگی از خطاها را نمی‌بینید. این تنها دلیل کافی است که پیاده‌سازی‌های ناقص را دور بیندازید.

window.onerror یا addEventListener؟

در بسیاری از نمونه‌کدها هنوز window.onerror را می‌بینید. هر دو راه به خطاهای همگام دسترسی دارند، ولی تفاوت‌هایشان در عمل مهم است.

window.onerror = function (message, source, lineno, colno, error) {
  // پنج آرگومان جدا، به‌جای یک شیء رویداد
  return false; // true یعنی پیام پیش‌فرض در کنسول چاپ نشود
};
  • فقط یک جا برای نوشتن. window.onerror یک ویژگی است. اگر اسکریپت دیگری بعد از شما مقدارش را عوض کند، شنوندهٔ شما بی‌صدا حذف می‌شود. addEventListener چند شنونده را کنار هم نگه می‌دارد.
  • خطای بارگذاری منابع. window.onerror این‌ها را نمی‌بیند، چون رویدادشان صعود نمی‌کند و فقط شنونده‌ای که در فاز capture ثبت شده به آن‌ها می‌رسد.
  • ساکت کردن کنسول. برگرداندن true از onerror، یا فراخوانی e.preventDefault() در شنونده، جلوی چاپ خطا در کنسول را می‌گیرد. بدون دلیل محکم این کار را نکنید؛ خطایی که در کنسول دیده نشود، دیباگ محلی را سخت می‌کند.

برای کد جدید addEventListener را انتخاب کنید. همین قاعده برای window.onunhandledrejection هم برقرار است.

یک پیاده‌سازی کامل

(function () {
  var sent = {};                       // جلوگیری از ارسال تکراری

  function report(payload) {
    var key = payload.message + '|' + (payload.line || '');
    if (sent[key]) return;             // همان خطا را بارها نفرست
    sent[key] = true;

    var body = JSON.stringify(Object.assign(payload, {
      url: location.href,
      userAgent: navigator.userAgent,
      time: Date.now()
    }));

    // sendBeacon هنگام بسته شدن صفحه هم کار می‌کند
    if (navigator.sendBeacon) navigator.sendBeacon('/api/errors', body);
    else fetch('/api/errors', { method: 'POST', body: body, keepalive: true });
  }

  window.addEventListener('error', function (e) {
    // خطای بارگذاری منابع، شکل متفاوتی دارد
    if (e.target && e.target !== window && e.target.tagName) {
      report({ type: 'resource', message: 'failed to load', src: e.target.src || e.target.href });
      return;
    }
    report({
      type: 'error',
      message: e.message,
      file: e.filename,
      line: e.lineno,
      column: e.colno,
      stack: e.error && e.error.stack
    });
  }, true);                            // true = فاز capture، برای گرفتن خطای منابع

  window.addEventListener('unhandledrejection', function (e) {
    var r = e.reason;
    report({
      type: 'rejection',
      message: (r && r.message) || String(r),
      stack: r && r.stack
    });
  });
})();

نکاتی که در پیاده‌سازی ساده جا می‌مانند

خطای Script error.

اگر خطایی در اسکریپتی از دامنهٔ دیگر رخ دهد، مرورگر به‌دلایل امنیتی جزئیاتش را پنهان می‌کند و فقط Script error. می‌دهد — بدون فایل، بدون خط، بدون stack.

رفعش دو بخش دارد: روی تگ اسکریپت ویژگی crossorigin="anonymous" بگذارید، و سرویس‌دهندهٔ آن فایل باید هدر Access-Control-Allow-Origin بدهد. اگر فایل‌ها را روی CDN می‌گذارید، این تنظیم را حتماً بررسی کنید. سازوکار پشتش همان CORS است.

خطای بارگذاری منابع

وقتی تصویری یا اسکریپتی بارگذاری نمی‌شود، رویداد error روی خود آن عنصر منتشر می‌شود و به window صعود نمی‌کند. برای همین در کد بالا شنونده با آرگومان سوم true ثبت شده تا در فاز capture اجرا شود.

حلقهٔ بی‌نهایت

اگر خودِ کد گزارش‌دهی خطا بدهد، خطای جدیدی می‌سازد که دوباره گزارش می‌شود. مکانیزم جلوگیری از تکرار در کد بالا این را می‌گیرد، ولی حواستان باشد که تابع report خودش هرگز نباید استثنا پرتاب کند.

سیل رخداد

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

خطاهایی که مال شما نیستند

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

چه چیزهایی به این شنونده‌ها نمی‌رسد

تور ایمنی سراسری همه‌چیز را نمی‌گیرد. این جاهای خالی را بشناسید تا وقتی خطایی در داشبورد نیامد، غافلگیر نشوید:

  • خطاهای پیش از ثبت شنونده. اگر کد تور ایمنی بعد از بقیهٔ اسکریپت‌ها بارگذاری شود، خطاهای آن فاصله گم می‌شوند. آن را اولین اسکریپت <head> بگذارید، بدون async و defer.
  • خطاهایی که فریم‌ورک خودش می‌گیرد. خطای رندری که Error Boundary در React گرفته، در build نهایی به window نمی‌رسد. Angular هم خطاها را به ErrorHandler خودش می‌دهد که به‌صورت پیش‌فرض فقط در کنسول چاپشان می‌کند. در Vue از app.config.errorHandler استفاده کنید. در همهٔ این‌ها، گزارش‌دهی را به قلاب خطای خود فریم‌ورک هم وصل کنید.
  • خطاهای بلعیده‌شده. یک catch خالی یا .catch(() => {}) خطا را برای همیشه پنهان می‌کند. اگر خطایی را می‌گیرید ولی نمی‌توانید درستش کنید، همان‌جا دستی گزارشش کنید.
  • پاسخ ناموفق HTTP. fetch برای پاسخ ۴۰۴ یا ۵۰۰ رد نمی‌شود؛ فقط خطای شبکه آن را reject می‌کند. اگر response.ok را بررسی نکنید، هیچ خطایی ساخته نمی‌شود که به تور ایمنی برسد.
  • iframe و Service Worker. هر iframe شیء window خودش را دارد و Service Worker در محدودهٔ سراسری جداگانه‌ای اجرا می‌شود. خطاهای آن‌ها به شنوندهٔ صفحهٔ اصلی نمی‌رسد؛ اگر منطق مهمی آنجاست، همان‌جا هم شنونده بگذارید.
  • console.error. چاپ پیام در کنسول خطا نیست و هیچ رویدادی منتشر نمی‌کند.

چه چیزی را همراه خطا بفرستیم

خودِ پیام خطا معمولاً برای حل کردن کافی نیست. چیزهایی که تفاوت بین «خطایی هست» و «می‌دانم چطور بازتولیدش کنم» را می‌سازند:

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

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

محدودسازی نرخ، جدی‌تر از آنچه فکر می‌کنید

مکانیزم سادهٔ «همان خطا را دو بار نفرست» برای شروع خوب است ولی کافی نیست. سناریویی که واقعاً پیش می‌آید: خطایی داخل تایمری که هر ثانیه اجرا می‌شود، با پیام کمی متفاوت در هر بار — مثلاً شامل عددی که تغییر می‌کند. مکانیزم تکراری‌یاب شما آن را خطای جدید می‌بیند و هزاران درخواست می‌فرستد.

الگویی که در عمل جواب می‌دهد، عقب‌نشینی نمایی است: رخداد اول، دوم، چهارم، هشتم و… از یک اثر انگشت را بفرستید و بقیه را بشمارید. یک خطا که ۵۰۰ بار تکرار شده، ۹ درخواست تولید می‌کند و شماره‌اش را هم همراه دارد.

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

چطور تستش کنیم

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

// ۱. خطای همگام
setTimeout(function () { throw new Error('تست همگام'); }, 0);

// ۲. Promise رد شده بدون catch
Promise.reject(new Error('تست ناهمگام'));

// ۳. خطای بارگذاری منبع
var img = new Image(); img.src = '/این-فایل-وجود-ندارد.png';
document.body.appendChild(img);

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

یک نمونهٔ واقعی: وقتی رفع Script error. سایت را از کار می‌اندازد

نشانه. سناریویی که زیاد پیش می‌آید: بیشتر گزارش‌ها Script error. است و تیم طبق توصیهٔ رایج، به تگ‌های اسکریپتی که از CDN می‌آیند crossorigin="anonymous" اضافه می‌کند. بلافاصله بعد از انتشار، بخشی از صفحه‌ها دیگر کار نمی‌کنند.

تشخیص. ویژگی crossorigin درخواست اسکریپت را به حالت CORS می‌برد. اگر CDN پاسخ را بدون هدر Access-Control-Allow-Origin بدهد، مرورگر اسکریپت را اصلاً اجرا نمی‌کند — نه اینکه فقط جزئیات خطا را پنهان کند. در کنسول خطای CORS دیده می‌شود و در زبانهٔ Network درخواست آن فایل ناموفق است.

رفع. ترتیب درست برعکس است: اول هدر را روی CDN فعال کنید و مطمئن شوید واقعاً برمی‌گردد، بعد ویژگی را به تگ اضافه کنید.

curl -sI -H "Origin: https://example.ir" https://cdn.example.ir/app.js | grep -i access-control

اگر هدر به‌جای * نام یک دامنهٔ مشخص را برمی‌گرداند، CDN باید Vary: Origin هم بفرستد. وگرنه ممکن است پاسخ کش‌شده برای یک دامنه به دامنهٔ دیگری تحویل داده شود و مشکل فقط گاهی ظاهر شود — بدترین نوع باگ برای ردیابی.

خطا را کجا بفرستیم؟

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

چیزهایی که لازم می‌شوند و معمولاً دیرتر کشف می‌شوند:

  • گروه‌بندی با اثر انگشت، تا هزاران رخداد یکسان یک ردیف شوند.
  • ترجمهٔ stack trace با source map، وگرنه چیزی جز t:1:24817 نمی‌بینید.
  • شمارش کاربران متأثر، نه فقط تعداد رخداد.
  • پاک‌سازی داده‌های شخصی پیش از ذخیره.
  • حذف خودکار داده‌های قدیمی.

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

مکمل ضروری: صدای کاربر

تور ایمنی سراسری هر خطای فنی را می‌گیرد، ولی دسته‌ای از مشکلات هیچ خطایی تولید نمی‌کنند: دکمه‌ای که پیدا نمی‌شود، متنی که گیج‌کننده است، فرمی که کار می‌کند ولی کسی تمامش نمی‌کند.

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

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

چرا e.error گاهی خالی است یا stack ندارد؟

دو دلیل رایج دارد. یا خطا از اسکریپت دامنهٔ دیگری آمده و مرورگر جزئیاتش را پنهان کرده، یا کد به‌جای شیء Error یک رشته پرتاب کرده، مثل throw 'failed'. مقداری که Error نباشد، stack ندارد. همیشه new Error(...) پرتاب کنید و Promise را هم با Error رد کنید.

در Node.js معادل این دو رویداد چیست؟

process.on('uncaughtException') و process.on('unhandledRejection'). از Node 15 به بعد، Promise ردشدهٔ مدیریت‌نشده به‌صورت پیش‌فرض پروسه را متوقف می‌کند. بعد از uncaughtException هم وضعیت برنامه قابل اعتماد نیست؛ خطا را ثبت کنید و بگذارید پروسه از نو راه‌اندازی شود، نه اینکه به کارش ادامه دهد.

آیا خطای نحوی (SyntaxError) هم گرفته می‌شود؟

اگر خطای نحوی در اسکریپت دیگری باشد، بله؛ مرورگر هنگام تجزیهٔ آن فایل رویداد error را منتشر می‌کند و آن اسکریپت اصلاً اجرا نمی‌شود. ولی اگر خطا در خودِ فایلی باشد که شنونده‌ها را ثبت می‌کند، هیچ‌چیز ثبت نمی‌شود. برای همین کد تور ایمنی را کوتاه و جدا از بقیهٔ کد نگه دارید.

جمع‌بندی

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

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

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

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

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

شروع رایگان