Error Boundary در React: صفحهٔ سفید را متوقف کنید

Error Boundary در React: صفحهٔ سفید را متوقف کنید
در این مقاله می‌خوانید
  1. چرا صفحه سفید می‌شود
  2. کامل‌ترین شکل
  3. استفاده
  4. چه چیزی را نمی‌گیرد
  5. معماری مرزها
  6. بازنشانی خودکار هنگام تغییر صفحه
  7. چطور تستش کنیم
  8. اشتباهات رایج
  9. نسخهٔ آماده
  10. رساندن خطای ناهمگام به مرز
  11. resetKeys: بازنشانی بدون از دست دادن state
  12. مرز خطا در کنار Suspense
  13. ثبت متمرکز در React 19
  14. پرسش‌های رایج
  15. آیا می‌شود مرز خطا را با کامپوننت تابعی و هوک نوشت؟
  16. مرز خطا خطای داخل useEffect را می‌گیرد؟
  17. آیا مرز خطا در React Native هم کار می‌کند؟
  18. ثبت کردن را فراموش نکنید
  19. منابع و مطالعهٔ بیشتر

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

مرز خطا مکانیزمی است که این را متوقف می‌کند.

چرا صفحه سفید می‌شود

از نسخهٔ ۱۶ به بعد، React اگر خطایی حین رندر رخ دهد و کسی نگیردش، کل درخت را از DOM حذف می‌کند. منطقش این است که رابط کاربریِ نیمه‌خراب می‌تواند دادهٔ غلط نشان دهد یا کاربر را به عمل اشتباهی بکشاند — و هیچ‌چیز نشان دادن، از آن امن‌تر است. رایج‌ترین این خطاها Cannot read properties of undefined است.

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

کامل‌ترین شکل

class ErrorBoundary extends React.Component {
  state = { error: null };

  static getDerivedStateFromError(error) {
    return { error };
  }

  componentDidCatch(error, info) {
    reportError(error, { componentStack: info.componentStack });
  }

  reset = () => this.setState({ error: null });

  render() {
    if (this.state.error) {
      return this.props.fallback
        ? this.props.fallback(this.state.error, this.reset)
        : <DefaultError onRetry={this.reset} />;
    }
    return this.props.children;
  }
}

سه نکته در این پیاده‌سازی که در نسخه‌های ساده‌تر نیست:

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

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

componentStack ثبت می‌شود. این چیزی است که می‌گوید خطا در کدام کامپوننت رخ داد — معمولاً مفیدتر از stack جاوااسکریپت، چون سلسله‌مراتب رابط کاربری را نشان می‌دهد. بدون Source Map، همین هم به نام‌های فشرده اشاره می‌کند.

استفاده

<ErrorBoundary fallback={(err, retry) => (
  <div className="err">
    <p>نمایش این بخش ممکن نشد.</p>
    <button onClick={retry}>تلاش دوباره</button>
  </div>
)}>
  <Comments postId={id} />
</ErrorBoundary>

چه چیزی را نمی‌گیرد

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

  • خطای هندلر رویداد. کلیک روی دکمه‌ای که خطا می‌دهد، خارج از چرخهٔ رندر است. try/catch لازم دارید.
  • کد ناهمگام. خطای داخل setTimeout، fetch یا callback ناهمگامی که در useEffect راه انداخته‌اید، پس از پایان رندر رخ می‌دهد.
  • رندر سمت سرور. مرزها فقط در مرورگر کار می‌کنند.
  • خطای خود مرز. اگر fallback شما خطا بدهد، به مرز بالاتر می‌رود. برای همین رابط جایگزین باید تا حد ممکن ساده باشد — بدون فراخوانی داده، بدون منطق پیچیده.

نتیجهٔ عملی: مرز خطا یک لایه از چند لایه است، نه راه‌حل کامل مدیریت خطا. لایه‌های دیگر را در مدیریت خطا در React مرور کرده‌ایم.

معماری مرزها

گذاشتن یک مرز دور کل برنامه، تقریباً هیچ چیزی حل نمی‌کند — همان صفحهٔ سفید را می‌گیرید با ظاهر بهتر. الگویی که واقعاً کار می‌کند سه سطح دارد:

سطح برنامه: آخرین خط دفاع. صفحه‌ای با پیام و دکمهٔ بارگذاری مجدد.

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

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

تفاوت عملی این است: در صفحهٔ محصول، اگر بخش «محصولات مشابه» خطا بدهد، کاربر همچنان می‌تواند همان محصول را بخرد.

بازنشانی خودکار هنگام تغییر صفحه

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

راه‌حل، وادار کردن React به ساختن نمونهٔ تازه با تغییر key است:

<ErrorBoundary key={location.pathname}>
  <Routes />
</ErrorBoundary>

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

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

مرز خطایی که تست نشده، معمولاً در لحظهٔ واقعی کار نمی‌کند. ساده‌ترین راه، کامپوننتی است که عمداً خطا می‌دهد:

function Boom({ when }) {
  if (when) throw new Error('تست مرز خطا');
  return <p>سالم</p>;
}

// در تست:
render(
  <ErrorBoundary fallback={() => <p>خطا رخ داد</p>}>
    <Boom when={true} />
  </ErrorBoundary>
);
expect(screen.getByText('خطا رخ داد')).toBeInTheDocument();

نکته‌ای که آزاردهنده است: React حتی وقتی مرز خطا را می‌گیرد، خطا را در کنسول هم چاپ می‌کند. در تست‌ها این خروجی را نویز می‌کند؛ می‌توانید موقتاً console.error را در همان تست ساکت کنید.

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

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

ثبت نکردن. پرتکرارترین اشتباه و در بخش بعد مفصل‌تر گفته شده.

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

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

نسخهٔ آماده

اگر نمی‌خواهید خودتان بنویسید، کتابخانهٔ react-error-boundary نسخهٔ بالغی از همین الگو را می‌دهد، به‌همراه هوک‌هایی برای انداختن خطا از کد ناهمگام به نزدیک‌ترین مرز — که یکی از محدودیت‌های اصلی مرزها را دور می‌زند.

رساندن خطای ناهمگام به مرز

مرز خطا خطای ناهمگام را خودش نمی‌بیند. چنین خطایی اگر جایی گرفته نشود، معمولاً به یک Promise ردشدهٔ مدیریت‌نشده تبدیل می‌شود و بی‌صدا می‌ماند. ولی می‌توانید آن را دستی به مرز برسانید: کافی است خطا در جریان رندر دوباره پرتاب شود. ترفند شناخته‌شده‌اش، پرتاب خطا داخل تابع به‌روزرسانی state است؛ React آن تابع را هنگام رندر اجرا می‌کند و خطا از همان‌جا به نزدیک‌ترین مرز می‌رسد:

function useThrowToBoundary() {
  const [, setState] = useState();
  return useCallback((error) => {
    setState(() => { throw error; });
  }, []);
}

function Comments({ postId }) {
  const throwToBoundary = useThrowToBoundary();
  const [comments, setComments] = useState([]);

  useEffect(() => {
    fetchComments(postId).then(setComments).catch(throwToBoundary);
  }, [postId, throwToBoundary]);
  // ...
}

هوک useErrorBoundary در کتابخانهٔ react-error-boundary همین کار را تمیزتر انجام می‌دهد: تابع showBoundary را برمی‌گرداند که در catch صدایش می‌زنید. فقط دقت کنید که این هوک زیر ErrorBoundary همان کتابخانه کار می‌کند، نه زیر کلاسی که خودتان نوشته‌اید.

یک هشدار: هر خطای ناهمگامی را به مرز نفرستید. اگر کاربر روی «ذخیره» زد و درخواست شکست خورد، جای پیام خطا کنار همان دکمه است، نه برداشتن کل بخش. این ترفند برای وقتی است که آن بخش بدون داده اصلاً چیزی برای نشان دادن ندارد.

resetKeys: بازنشانی بدون از دست دادن state

ترفند key که بالاتر دیدیم کار می‌کند، ولی هزینه دارد: با هر تغییر key، کل زیردرخت از نو ساخته می‌شود و state کامپوننت‌های داخلش — متن نیمه‌نوشتهٔ یک فرم، موقعیت اسکرول یک فهرست — از دست می‌رود، حتی وقتی خطایی در کار نبوده است.

react-error-boundary برای این گزینهٔ resetKeys را دارد: آرایه‌ای از مقادیر که اگر مرز در حالت خطا باشد و یکی از آن‌ها عوض شود، مرز خودش را بازنشانی می‌کند. وقتی مرز سالم است، تغییر این مقادیر هیچ اثری ندارد.

import { ErrorBoundary } from 'react-error-boundary';

function CommentsError({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>نمایش نظرات ممکن نشد.</p>
      <button onClick={resetErrorBoundary}>تلاش دوباره</button>
    </div>
  );
}

<ErrorBoundary
  FallbackComponent={CommentsError}
  resetKeys={[postId]}
  onError={(error, info) => reportError(error, { componentStack: info.componentStack })}
>
  <Comments postId={postId} />
</ErrorBoundary>

نتیجه: اگر نظرات پست ۱۲ خطا داد و کاربر به پست ۱۳ رفت، مرز خودبه‌خود دوباره تلاش می‌کند. مقایسهٔ مقادیر با Object.is انجام می‌شود، پس در resetKeys مقدار ساده بگذارید، نه شیء یا آرایه‌ای که در هر رندر از نو ساخته می‌شود؛ وگرنه مرزِ در حالت خطا با هر رندر والد بی‌دلیل دوباره تلاش می‌کند.

مرز خطا در کنار Suspense

Suspense و مرز خطا مکمل هم‌اند: یکی حالت «در حال بارگذاری» را مدیریت می‌کند و دیگری حالت «نشد». در React 19 اگر Promiseای که به use داده‌اید رد شود، خطا به نزدیک‌ترین مرز می‌رود. چیدمان معمول این است:

<ErrorBoundary fallback={(err, retry) => <CommentsError onRetry={retry} />}>
  <Suspense fallback={<Spinner />}>
    <Comments commentsPromise={commentsPromise} />
  </Suspense>
</ErrorBoundary>

دامی که اینجا هست: دکمهٔ «تلاش دوباره» ممکن است هیچ کاری نکند. reset فقط مرز را از حالت خطا بیرون می‌آورد؛ Comments دوباره با همان Promise قبلی رندر می‌شود که هنوز رد شده است، و همان خطا فوراً برمی‌گردد. برای تلاش واقعی، باید همراه با بازنشانی مرز یک Promise تازه بسازید — مثلاً در والد. با react-error-boundary، جای این کار callback onReset است.

ثبت متمرکز در React 19

از React 19، createRoot و hydrateRoot گزینه‌هایی دارند که ثبت خطا را از تک‌تک مرزها بیرون می‌آورند:

const root = createRoot(document.getElementById('root'), {
  onCaughtError(error, errorInfo) {
    // یک مرز خطا را گرفته و رابط جایگزین نشان داده است
    reportError(error, { componentStack: errorInfo.componentStack, caught: true });
  },
  onUncaughtError(error, errorInfo) {
    // هیچ مرزی خطا را نگرفته و React درخت را برداشته است
    reportError(error, { componentStack: errorInfo.componentStack, caught: false });
  },
});
root.render(<App />);

مزیتش این است که حتی مرزی که کسی در آن componentDidCatch را فراموش کرده، از ثبت جا نمی‌ماند. دو نکته: این گزینه‌ها رفتار پیش‌فرض React را جایگزین می‌کنند، پس اگر هنوز چاپ خطا در کنسول را می‌خواهید، خودتان console.error را صدا بزنید. و اگر هم اینجا ثبت می‌کنید و هم در componentDidCatch، هر خطا دو بار می‌رسد — یکی را انتخاب کنید.

بدون این گزینه‌ها، React 19 خطای گرفته‌نشده را با window.reportError گزارش می‌کند و شنوندهٔ سراسری error روی window آن را می‌بیند. ولی خطایی که مرز گرفته فقط با console.error چاپ می‌شود و به آن شنونده نمی‌رسد.

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

آیا می‌شود مرز خطا را با کامپوننت تابعی و هوک نوشت؟

نه. حتی در React 19 هم هوکی معادل getDerivedStateFromError یا componentDidCatch وجود ندارد و مرز خطا باید کلاس باشد. ولی لازم نیست بیش از یک بار بنویسیدش: یک کلاس بسازید — یا از react-error-boundary استفاده کنید — و بقیهٔ کد را تابعی نگه دارید.

مرز خطا خطای داخل useEffect را می‌گیرد؟

بستگی دارد خطا کجا رخ دهد. اگر خطا مستقیم و همگام در بدنهٔ effect پرتاب شود، مرز آن را می‌گیرد، چون خود React effect را اجرا می‌کند. ولی خطایی که داخل callback یک then یا setTimeout رخ دهد، بیرون از دسترس React است و مرز آن را نمی‌بیند — مگر با ترفندی که بالاتر گفتیم.

آیا مرز خطا در React Native هم کار می‌کند؟

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

ثبت کردن را فراموش نکنید

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

این بدتر از صفحهٔ سفید است، چون صفحهٔ سفید دست‌کم باعث می‌شود کسی زنگ بزند.

پس componentDidCatch باید همیشه خطا را جایی بفرستد که واقعاً نگاهش می‌کنید، همراه با componentStack و اطلاعات کاربر. مرز خطا برای کاربر است؛ ثبت کردن برای شما.

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

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

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

شروع رایگان