مدیریت خطا در React: از componentDidCatch تا امروز

مدیریت خطا در React: از componentDidCatch تا امروز
در این مقاله می‌خوانید
  1. سه دستهٔ خطا در React
  2. ۱. خطای رندر
  3. ۲. خطای رویداد
  4. ۳. خطای ناهمگام
  5. مرز خطا برای دستهٔ اول
  6. کجا بگذاریمش
  7. دستهٔ دوم: خطای رویداد
  8. دستهٔ سوم: خطای ناهمگام
  9. در Next.js فرق می‌کند
  10. فرم‌ها و Actionها در React 19
  11. کتابخانه‌های دریافت داده
  12. تنظیم سراسری در React Query
  13. سه حالت، نه دو حالت
  14. در production
  15. اشتباهات رایج
  16. جمع‌بندی
  17. منابع و مطالعهٔ بیشتر

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

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

سه دستهٔ خطا در React

تفکیک این سه، کلید فهمیدن بقیهٔ مقاله است، چون هر کدام مکانیزم متفاوتی می‌خواهند.

۱. خطای رندر

حین ساختن رابط کاربری رخ می‌دهد و همان چیزی است که صفحهٔ سفید می‌سازد. رایج‌ترین علتش Cannot read properties of undefined است.

function Profile({ user }) {
  return <h1>{user.name}</h1>;   // اگر user نباشد، کل درخت می‌رود
}

۲. خطای رویداد

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

۳. خطای ناهمگام

در useEffect، در fetch، یا در تایمر. این‌ها هم از دست مرز خطا در می‌روند و معمولاً بی‌صداترین دسته‌اند. جزئیاتش را در Unhandled Promise Rejection ببینید.

مرز خطا برای دستهٔ اول

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

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };        // رابط جایگزین را نشان بده
  }

  componentDidCatch(error, info) {
    reportError(error, info.componentStack);   // و خبرش کن
  }

  render() {
    if (this.state.hasError) return this.props.fallback;
    return this.props.children;
  }
}

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

کجا بگذاریمش

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

الگوی مؤثر، چند لایه است:

<ErrorBoundary fallback={<FullPageError />}>        {/* آخرین خط دفاع */}
  <Layout>
    <ErrorBoundary fallback={<p>نمایش نظرات ممکن نشد</p>}>
      <Comments />                                  {/* فقط این بخش می‌رود */}
    </ErrorBoundary>
  </Layout>
</ErrorBoundary>

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

دستهٔ دوم: خطای رویداد

چون مرز خطا این‌ها را نمی‌گیرد، باید صریح مدیریتشان کنید:

async function handleSubmit() {
  setStatus('loading');
  try {
    const res = await api.save(form);
    if (!res.ok) throw new Error('HTTP ' + res.status);
    setStatus('done');
  } catch (e) {
    setStatus('error');     // به کاربر بگو
    reportError(e);         // و خودت هم بدان
  }
}

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

دستهٔ سوم: خطای ناهمگام

مورد کلاسیک، useEffectای است که داده می‌گیرد:

useEffect(() => {
  let cancelled = false;
  (async () => {
    try {
      const res = await fetch('/api/user');
      if (!res.ok) throw new Error('HTTP ' + res.status);
      const data = await res.json();
      if (!cancelled) setUser(data);
    } catch (e) {
      if (!cancelled) { setError(e); reportError(e); }
    }
  })();
  return () => { cancelled = true; };   // از به‌روزرسانی پس از unmount جلوگیری کن
}, []);

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

در Next.js فرق می‌کند

اگر از Next.js استفاده می‌کنید، بخشی از کد روی سرور اجرا می‌شود و مرزهای خطای React آنجا کار نمی‌کنند. Next الگوی خودش را دارد — فایل‌های ویژه‌ای که به‌عنوان مرز عمل می‌کنند:

// app/dashboard/error.jsx
'use client';                       // مرز خطا حتماً کلاینتی است

export default function Error({ error, reset }) {
  useEffect(() => { reportError(error); }, [error]);
  return (
    <div>
      <p>بارگذاری این بخش ممکن نشد.</p>
      <button onClick={reset}>تلاش دوباره</button>
    </div>
  );
}

این فایل به‌طور خودکار مرز خطای همان مسیر و زیرمسیرهایش می‌شود. نکتهٔ مهم: خطای خود layout را نمی‌گیرد — برای آن به فایلی در سطح بالاتر نیاز دارید.

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

این شناسه در error.digest است و Next آن را دقیقاً برای تطبیق با خطای متناظر در لاگ سرور می‌سازد. پس آن را همراه خطا ثبت کنید. بدون آن، گزارشی که از مرورگر می‌رسد فقط می‌گوید «چیزی روی سرور شکست» و برای پیدا کردن خط درست لاگ باید حدس بزنید — همان وضعیتی که دیباگ در production را کند می‌کند.

فرم‌ها و Actionها در React 19

React 19 راه تازه‌ای برای ارسال فرم آورده است: تابعی که به action فرم یا به useActionState می‌دهید. اینجا مدیریت خطا قاعدهٔ خودش را دارد و بهتر است از اول درست چیده شود.

دو نوع خطا را از هم جدا کنید. خطای مورد انتظار — فیلد نامعتبر، ایمیل تکراری، پاسخ ۴۲۲ — بخشی از کار عادی فرم است. آن را به‌صورت مقدار برگردانید تا کنار همان فرم نشان داده شود. خطای غیرمنتظره — سرور از کار افتاده، پاسخ ۵۰۰ — را پرتاب کنید؛ React آن را به نزدیک‌ترین مرز خطا می‌فرستد.

async function saveProfile(prevState, formData) {
  const res = await fetch('/api/profile', { method: 'POST', body: formData });
  if (res.status === 422) {
    return { error: 'ایمیل واردشده معتبر نیست' };     // مورد انتظار: برگردان
  }
  if (!res.ok) throw new Error('HTTP ' + res.status);  // غیرمنتظره: به مرز خطا
  return { error: null };
}

function ProfileForm() {
  const [state, formAction, isPending] = useActionState(saveProfile, { error: null });
  return (
    <form action={formAction}>
      <input name="email" type="email" />
      {state.error && <p role="alert">{state.error}</p>}
      <button disabled={isPending}>ذخیره</button>
    </form>
  );
}

نتیجهٔ عملی: فرمی که از Action استفاده می‌کند باید داخل یک مرز خطا باشد. وگرنه خطای غیرمنتظره به هیچ مرزی نمی‌رسد و همان قاعدهٔ اول این مقاله اجرا می‌شود: کل درخت برداشته می‌شود. در Server Actionهای Next.js هم همین تفکیک توصیه شده است: خطای مورد انتظار را برگردانید، نه اینکه پرتابش کنید.

کتابخانه‌های دریافت داده

اگر از React Query یا SWR استفاده می‌کنید، بخش بزرگی از مدیریت خطای ناهمگام را خودشان انجام می‌دهند و کد شما ساده‌تر می‌شود:

const { data, error, isLoading, refetch } = useQuery({
  queryKey: ['user', id],
  queryFn: fetchUser,
});

if (isLoading) return <Spinner />;
if (error)     return <Retry onClick={refetch} />;
return <Profile user={data} />;

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

تنظیم سراسری در React Query

در نسخهٔ ۵ (TanStack Query)، این تنظیم سراسری با QueryCache و MutationCache انجام می‌شود:

import { QueryClient, QueryCache, MutationCache } from '@tanstack/react-query';

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => reportError(error, { queryKey: query.queryKey }),
  }),
  mutationCache: new MutationCache({
    onError: (error) => reportError(error),
  }),
});

این callbackها برای هر درخواستِ شکست‌خورده یک بار صدا زده می‌شوند — پس از تمام شدن تلاش‌های مجدد خودکار — نه یک بار برای هر کامپوننتی که از آن کوئری استفاده می‌کند. پس ثبت تکراری ندارید. queryKey را هم بفرستید؛ بدون آن نمی‌دانید کدام درخواست شکست خورده است.

اگر می‌خواهید خطای یک کوئری خاص به‌جای نمایش موضعی به مرز خطا برود، گزینهٔ throwOnError: true را روی همان کوئری بگذارید. برای داده‌ای که صفحه بدون آن معنی ندارد — مثلاً خود محصول در صفحهٔ محصول — این انتخاب معقولی است. برای بخش‌های فرعی، نمایش موضعی بهتر است.

سه حالت، نه دو حالت

رایج‌ترین ریشهٔ خطای رندر در React این است که فقط دو حالت در نظر گرفته می‌شود: داده هست یا نیست. در واقع سه حالت وجود دارد:

if (loading) return <Spinner />;
if (error)   return <Retry onClick={refetch} />;
return <Profile user={user} />;

اگر حالت میانی را ننویسید، کامپوننت در اولین رندر با دادهٔ خالی اجرا می‌شود و همان خطای Cannot read properties of undefined را می‌گیرید.

در production

سه نکته که بدون آن‌ها، خطاهای React عملاً غیرقابل ردیابی می‌مانند:

پیام‌های خطا فشرده‌اند. React در حالت production پیام‌ها را به شمارهٔ کد تبدیل می‌کند تا حجم کم شود. لینکی که همراهش می‌آید، متن کامل را نشان می‌دهد.

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

Source map لازم دارید، وگرنه stack به کد فشرده اشاره می‌کند و چیزی نمی‌گوید.

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

این الگوها در بازبینی کد React زیاد دیده می‌شوند و هر کدام خطا را از دید شما پنهان می‌کنند.

try/catch دور JSX. کد زیر ظاهراً امن است ولی خطای Profile را نمی‌گیرد:

function Page() {
  try {
    return <Profile />;      // Profile اینجا رندر نمی‌شود
  } catch (e) {
    return <p>خطا</p>;
  }
}

این خط فقط توصیفی از کامپوننت می‌سازد؛ React خود Profile را بعداً و بیرون از این بلوک رندر می‌کند. برای خطای فرزندان، فقط مرز خطا جواب می‌دهد.

تابع async مستقیم در useEffect. با نوشتن useEffect(async () => { … })، effect به‌جای تابع cleanup یک Promise برمی‌گرداند. React در حالت توسعه هشدار می‌دهد و دیگر جایی برای برگرداندن cleanup نمی‌ماند. تابع async را مثل نمونهٔ بالا داخل effect تعریف و صدا بزنید.

try بدون await. در هندلر رویداد، try { save(); } catch (e) { … } فقط خطای همگام را می‌گیرد. اگر save یک Promise برگرداند، رد شدنش از این catch عبور می‌کند و مدیریت‌نشده می‌ماند. یا await کنید یا .catch بگذارید.

catch خالی. نوشتن catch (e) {} برای ساکت کردن یک هشدار مزاحم، رایج‌ترین راه گم کردن یک باگ واقعی است. اگر واقعاً می‌خواهید خطایی را نادیده بگیرید، دلیلش را در کامنت بنویسید و دست‌کم ثبتش کنید.

پرتاب رشته به‌جای Error. throw 'نشد' هیچ stack ندارد و ابزار رصد نمی‌تواند بگوید از کجا آمده است. همیشه throw new Error('…') بنویسید.

فراموش کردن global-error در Next.js. گفتیم که error.jsx خطای layout هم‌سطح خودش را نمی‌گیرد. برای خطای layout ریشه، فایل app/global-error.jsx لازم است. این فایل جای layout ریشه را می‌گیرد، پس باید تگ‌های html و body را خودش داشته باشد.

جمع‌بندی

مدیریت خطا در React سه لایه دارد و هر لایه مکانیزم خودش را می‌خواهد: مرز خطا برای رندر، try/catch برای رویدادها، و مدیریت صریح برای کد ناهمگام. پوشش یکی از این سه، دو تای دیگر را پوشش نمی‌دهد. برای شناخت خود خطاها، راهنمای جامع خطاهای جاوااسکریپت را ببینید.

و لایهٔ چهارمی هم هست که بیرون از React می‌ماند: شنوندهٔ سراسری خطا، برای هر چیزی که از این سه رد شده باشد.

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

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

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

شروع رایگان