---
title: "أضف حدًّا للأخطاء في React وسجّل الأخطاء التي تفوته"
description: "يلتقط حدّ الأخطاء (error boundary) في React الأخطاء أثناء العرض ويعرض واجهة بديلة. إليك الصنف، والأخطاء التي تفوته، وطريقة إرسال كل خطأ إلى LogBrew، من اختبار على React 19.3."
canonical: "https://logbrew.co/ar/guides/react-error-boundary"
last_updated: "2026-11-21"
---

# أضف حدًّا للأخطاء في React وسجّل الأخطاء التي تفوته

يلتقط حدّ الأخطاء (error boundary) في React الأخطاء أثناء العرض ويعرض واجهة بديلة. إليك الصنف، والأخطاء التي تفوته، وطريقة إرسال كل خطأ إلى LogBrew، من اختبار على React 19.3.

اختُبر في 21 نوفمبر 2026 باستخدام React 19.3.1 وVite 8.3.8 وChrome 156 و@logbrew/react 0.1.6 و@logbrew/sdk 0.1.47 وlogbrew CLI 0.1.96

بقلم [Furkan Erday](https://github.com/furkanerday). Furkan Erday مؤسس LogBrew، ويبني LogBrew كل يوم باستخدام Claude Code وCodex.

Canonical: https://logbrew.co/ar/guides/react-error-boundary

## أي أخطاء React تعرض واجهة بديلة وتصل إلى LogBrew

| مكان رمي الخطأ | عرض الواجهة البديلة | مشكلة في LogBrew |
| --- | --- | --- |
| العرض، داخل `LogBrewErrorBoundary` | نعم | نعم |
| `useEffect`، داخل الحدّ | نعم | نعم |
| العرض، دون حدّ | لا، الجذر فارغ | نعم، عبر خيارات الجذر |
| معالج `onClick` | لا | لا |
| معالج غير متزامن، بعد `await` | لا | لا |
| `onClick` مع `captureReactError()` | لا | نعم |

6 أخطاء في بناء إنتاج واحد من Vite مع React 19.3.1 و@logbrew/react 0.1.6.

## اكتب حدًّا للأخطاء

### اكتب الحدّ مكوّنًا من نوع صنف

لا يوفّر React خطافًا لهذا، لذلك يكون حدّ الأخطاء صنفًا. ينقله `getDerivedStateFromError` إلى الواجهة البديلة في العرض التالي. ويتلقّى `componentDidCatch` الخطأ و`info.componentStack`، أي قائمة المكوّنات فوق المكوّن الذي رمى الخطأ.

```bash
import { Component } from "react";

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

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

  componentDidCatch(error, info) {
    console.log("caught:", error.message);
    console.log("in:", info.componentStack.split("\n")[1].trim());
  }

  render() {
    if (this.state.error) return <p role="alert">Could not load the taps.</p>;
    return this.props.children;
  }
}
```

### غلّف جزء الصفحة الذي قد يفشل

يقرأ `TapList` القيمة `taps.map` عندما تكون `taps` مفقودة، فيرمي خطأً أثناء العرض. عرض الحدّ `Could not load the taps.`، وبقي العنوان `Taproom` ظاهرًا. وفي وضع التطوير طبع React الخطأ أيضًا مع `The above error occurred in the <TapList> component`.

```bash
// TapList.jsx
export function TapList({ taps }) {
  return <ul>{taps.map((tap) => <li key={tap}>{tap}</li>)}</ul>;
}

// App.jsx
import { ErrorBoundary } from "./ErrorBoundary.jsx";
import { TapList } from "./TapList.jsx";

export function App() {
  return (
    <main>
      <h1>Taproom</h1>
      <ErrorBoundary>
        <TapList />
      </ErrorBoundary>
    </main>
  );
}
```

المخرجات

```text
caught: Cannot read properties of undefined (reading 'map')
in: at TapList (http://127.0.0.1:25174/guide/TapList.jsx:3:27)
```

### الخطأ في معالج الأحداث يتجاوز الحدّ

يستدعي React `onClick` خارج العرض، لذلك لم يتلقَّ الحدّ الخطأ أبدًا. بقي الزر في الصفحة، وطبع المتصفح خطأً غير ملتقط. والخطأ بعد `await` فعل الشيء نفسه.

```bash
export function PourButton() {
  return (
    <button onClick={() => { throw new Error("pour failed"); }}>Pour</button>
  );
}

// main.jsx
createRoot(document.getElementById("root")).render(
  <ErrorBoundary>
    <PourButton />
  </ErrorBoundary>
);
```

المخرجات

```text
Uncaught Error: pour failed
    at onClick (http://127.0.0.1:25174/guide/PourButton.jsx:6:10)
```

### مرّر خطأ المعالج إلى الحدّ عبر الحالة

التقط الخطأ في المعالج، واحفظه عبر `setError`، ثم ارمه في العرض التالي. عندها يعرض الحدّ واجهته البديلة ويتلقّى الخطأ في `componentDidCatch`.

```bash
import { useState } from "react";

export function SafePourButton() {
  const [error, setError] = useState(null);
  if (error) throw error;

  function pour() {
    try {
      throw new Error("pour failed");
    } catch (caught) {
      setError(caught);
    }
  }

  return <button onClick={pour}>Pour</button>;
}
```

المخرجات

```text
caught: pour failed
in: at SafePourButton (http://127.0.0.1:25174/guide/SafePourButton.jsx:7:28)
```

### دون حدّ، يزيل React الشجرة كلها

عندما لا يلتقط أي حدّ خطأ العرض، يفكّ React 19 تركيب الجذر. أصبح العنصر `root` فارغًا، واختفى العنوان أيضًا. وطبع React الخطأ وتحذيرًا يطلب إضافة حدّ للأخطاء.

```bash
import { createRoot } from "react-dom/client";
import { TapList } from "./TapList.jsx";

createRoot(document.getElementById("root")).render(
  <main>
    <h1>Taproom</h1>
    <TapList />
  </main>
);
```

المخرجات

```text
Uncaught TypeError: Cannot read properties of undefined (reading 'map')
An error occurred in the <TapList> component. Consider adding an error boundary to your tree to customize error handling behavior.
Visit https://react.dev/link/error-boundaries to learn more about error boundaries.
```

## أرسل أخطاء React إلى LogBrew

### ثبّت الحزم

توفّر `@logbrew/react` المكوّن Provider وحدّ الأخطاء وخيارات الجذر. استخدم مفتاح متصفح من مشروعك في LogBrew قيمةً لـ `clientKey`.

```bash
npm install @logbrew/sdk @logbrew/react react
```

### أنشئ العميل وعنصر transport

يحتفظ العميل بالأحداث في طابور حتى تستدعي `client.flush(transport)`. يجب أن يعيد transport القيمة `{ statusCode }`. عندما أعاد transport الخاص بنا استجابة `fetch` كما هي، فشل flush مع `invalid transport response`. اضبط `VITE_LOGBREW_ENDPOINT` على `https://api.logbrew.co/v1/events`. أرسلنا إلى خادم LogBrew محلي.

```bash
import { createLogBrewReactClient } from "@logbrew/react";

export const client = createLogBrewReactClient({
  clientKey: import.meta.env.VITE_LOGBREW_CLIENT_KEY
});

export const transport = {
  async send(apiKey, body) {
    const response = await fetch(import.meta.env.VITE_LOGBREW_ENDPOINT, {
      method: "POST",
      headers: {
        authorization: `Bearer ${apiKey}`,
        "content-type": "application/json",
      },
      body
    });
    return { statusCode: response.status };
  }
};

export function send() {
  return client
    .flush(transport)
    .then((result) => console.log("sent", JSON.stringify(result)));
}
```

### ضع LogBrewErrorBoundary داخل LogBrewProvider

يأخذ `LogBrewErrorBoundary` العميل من `LogBrewProvider`. دون Provider عرض الواجهة البديلة لكنه لم يرسل شيئًا، وتلقّى `onCaptureError` الرسالة `captureReactError requires a client`. يعمل `onError` بعد الالتقاط، لذلك نفّذ flush هناك.

```bash
import { LogBrewErrorBoundary, LogBrewProvider } from "@logbrew/react";
import { client, send } from "./logbrew.js";
import { TapList } from "./TapList.jsx";

export function App() {
  return (
    <LogBrewProvider client={client}>
      <LogBrewErrorBoundary
        fallback={({ error, resetError }) => (
          <div role="alert">
            <p>Could not load the taps: {error.message}</p>
            <button onClick={resetError}>Try Again</button>
          </div>
        )}
        onError={send}
      >
        <TapList />
      </LogBrewErrorBoundary>
    </LogBrewProvider>
  );
}
```

المخرجات

```text
sent {"statusCode":200,"attempts":1,"batches":1}
```

### التقط الأخطاء التي لم يلتقطها أي حدّ

يمنح `createLogBrewReactRootOptions()` الدالة `createRoot` دوال رد النداء للأخطاء. وقد سجّل خطأ العرض الذي لم يحطه أي حدّ. ويتخطّى الأخطاء التي أرسلها `LogBrewErrorBoundary` من قبل، فيصل كل خطأ مرة واحدة.

```bash
import { createRoot } from "react-dom/client";
import { createLogBrewReactRootOptions } from "@logbrew/react";
import { client, send } from "./logbrew.js";
import { TapList } from "./TapList.jsx";

createRoot(
  document.getElementById("root"),
  createLogBrewReactRootOptions(client, { onUncaughtError: send })
).render(<TapList />);
```

المخرجات

```text
sent {"statusCode":200,"attempts":1,"batches":1}
```

### أبلغ عن أخطاء المعالجات عبر captureReactError()

لا يتلقّى الحدّ ولا دالة رد النداء في الجذر خطأ المعالج، لذلك التقطه ومرّره إلى `captureReactError()`. وتبقى قيمة `metadata` التي تمرّرها على المشكلة.

```bash
import { captureReactError } from "@logbrew/react";
import { client, send } from "./logbrew.js";

export function PayButton() {
  async function pay() {
    try {
      await Promise.resolve();
      throw new Error("payment declined");
    } catch (error) {
      captureReactError(client, error, { metadata: { action: "pay" } });
      send();
    }
  }

  return <button onClick={pay}>Pay</button>;
}
```

المخرجات

```text
sent {"statusCode":200,"attempts":1,"batches":1}
```

### اقرأ المشكلات من جديد

قرأنا المشروع بمفتاح قراءة. جاء خطأ العرض داخل الحدّ والخطأ نفسه دون حدّ من `TapList.jsx`، لذلك أصبحا مشكلة واحدة بتكرارين. وأصبح خطأ المعالج مشكلة مستقلة.

```bash
logbrew issues --since 3h
```

المخرجات

```text
Issues (2)
- 1613a62e-31a3-5045-a144-c9c593760bff unresolved error priority=medium React error: payment declined occurrences=1 users=unknown last_seen=2026-11-21T06:35:49.154Z service=unknown_service trace=2ca253b519dfa2866268889760e5f2a0 assignee=unassigned [unversioned / production]
- f9eb7448-fab2-5d52-82f3-592a3b680a08 unresolved error priority=medium React error: Cannot read properties of undefined (reading 'map') occurrences=2 users=unknown last_seen=2026-11-21T06:35:43.870Z service=unknown_service trace=225e883023acc9c768da676fedd8e2c1 assignee=unassigned [unversioned / production]
```

## ما رأيناه في الاختبار

أنشأنا تطبيق Vite واحدًا مع React 19.3.1 و@logbrew/react 0.1.6، وشغّلنا كل حالة في Chrome مع خادم LogBrew محلي. المخرجات أعلاه من خادم التطوير في Vite. وشغّلنا الحالات نفسها في بناء الإنتاج، فكانت النتائج نفسها.

لم يصل إلى الحدّ إلا الأخطاء أثناء العرض وداخل `useEffect`. أما الأخطاء في `onClick` وبعد `await` فلم تصل إلى أي حدّ ولا إلى أي دالة رد نداء في الجذر. ولم يرسلها إلا `captureReactError()`.

|  | `LogBrewErrorBoundary` | `onUncaughtError` |
| --- | --- | --- |
| خطأ عرض داخل الحدّ | نعم | لا |
| خطأ عرض دون حدّ | لا | نعم |
| خطأ في معالج الأحداث | لا | لا |

## أعد ضبط الحدّ وحاول مجددًا

تتلقّى الواجهة البديلة في `LogBrewErrorBoundary` الدالة `resetError`، التي تعيد عرض المكوّنات الأبناء. إذا رمى الابن الخطأ مجددًا، يعرض الحدّ الواجهة البديلة مرة أخرى ويرسل حدثًا إضافيًا واحدًا.

لذلك أصلح السبب قبل المحاولة، مثلًا حمّل البيانات من جديد. في اختبارنا، عرضت المحاولة الجديدة القائمة عندما كانت البيانات متاحة.

|  | عرض الواجهة البديلة | إرسال حدث |
| --- | --- | --- |
| أول خطأ في العرض | نعم | نعم |
| `Try Again`، والابن يرمي الخطأ مجددًا | نعم | نعم |
| `Try Again`، والابن يُعرض | لا | لا |

## ما يسجّله LogBrew

يصبح كل خطأ في React مشكلة عنوانها `React error:` ثم رسالة الخطأ. يسجّل الحدّ الآلية `react.error_boundary` مع `handled: true`. وتسجّل خيارات الجذر `react.uncaught_error` مع `handled: false`.

يجمّع LogBrew أخطاء React حسب نوع الخطأ وملف أول إطار في المكدّس. في بناء الإنتاج لدينا، جاءت 5 أحداث `Error` برسائل مختلفة، مثل `keg sensor offline` و`tap list not loaded`، من ملف حزمة واحد فأصبحت مشكلة واحدة. وفي وضع التطوير يكون لكل مكوّن ملفه الخاص، لذلك بقيت المشكلات منفصلة.

- `LogBrewErrorBoundary`
  - `mechanism`: `react.error_boundary`
  - `handled`: `true`
  - المشكلة: `React error: Cannot read properties of undefined (reading 'map')`
- `createLogBrewReactRootOptions()`
  - `mechanism`: `react.uncaught_error`
  - `handled`: `false`
  - إطارات المكدّس: 10
- `captureReactError()`
  - المشكلة: `React error: payment declined`
  - `metadata.action`: `pay`
  - مفتاح التجميع: `react.error:Error:…/HandlerButton.jsx`

## أسئلة شائعة

### ما حدّ الأخطاء في React؟

مكوّن من نوع صنف فيه `getDerivedStateFromError` أو `componentDidCatch`. عندما يرمي ابن خطأً أثناء العرض، يعرض React الواجهة البديلة للحدّ ويُبقي بقية الصفحة.

### هل أستطيع كتابة حدّ للأخطاء باستخدام الخطافات؟

لا. لا يوفّر React خطافًا لهذا، لذلك يكون الحدّ صنفًا. اكتبه مرة واحدة، أو استخدم `LogBrewErrorBoundary`، وضعه حول مكوّنات الدوال.

### لماذا لا يلتقط حدّ الأخطاء الخطأ؟

رُمي الخطأ خارج العرض، غالبًا في معالج أحداث أو بعد `await`. التقطه هناك وأبلغ عنه عبر `captureReactError()`، أو احفظه في الحالة وارمه أثناء العرض.

### أين أضع حدود الأخطاء؟

حول كل جزء من الصفحة قد يفشل وحده، مثل قائمة تحمّل البيانات، لتبقى بقية الصفحة تعمل. وضع حدًّا واحدًا قرب الجذر أيضًا، لأن الخطأ الذي لا يلتقطه أي حدّ يزيل الشجرة كلها.

### كيف أسجّل الأخطاء من حدّ الأخطاء؟

أرسلها من `componentDidCatch`، أو استخدم `LogBrewErrorBoundary` داخل `LogBrewProvider`. وأضف `createLogBrewReactRootOptions()` إلى `createRoot` للأخطاء التي لم يلتقطها أي حدّ.

## شاهد كل خطأ في React مع مكدّس المكوّنات

يسجّل LogBrew كل خطأ عرض في React مع مكدّس المكوّنات، ويجمع التكرارات في مشكلة واحدة. ابدأ بخطة مجانية سخية دون بطاقة.

[ابدأ مجانًا](https://logbrew.co/ar)

## المصادر

- [React docs, Catching rendering errors with an Error Boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
- [React docs, createRoot parameters](https://react.dev/reference/react-dom/client/createRoot#parameters)
- [reactjs/react.dev#8157](https://github.com/reactjs/react.dev/issues/8157)

## إرشادات أخرى للوكلاء وPython وNode.js وReact

- [أضف خادم MCP إلى Claude Code وCodex](https://logbrew.co/ar/guides/mcp-server-claude-code-codex)
- [استخدم AGENTS.md في Claude Code وCodex](https://logbrew.co/ar/guides/agents-md)
- [أصلح خطأ Claude overloaded 529 وخطأ rate limit 429](https://logbrew.co/ar/guides/claude-overloaded-rate-limit-error)
- [إعداد Python logging بمستويات السجل الصحيحة والتقاط الاستثناءات](https://logbrew.co/ar/guides/python-logging)
- [التسجيل المنظّم بتنسيق سجل ومستويات سجل يمكنك البحث فيها حسب الحقل](https://logbrew.co/ar/guides/structured-logging)
- [إعداد السجلات في Node.js باستخدام Pino أو Winston دون أن تفقد أي خطأ](https://logbrew.co/ar/guides/node-logging)
- [أعدّ سجلات Django واحفظ تتبّع المكدّس لكل خطأ 500](https://logbrew.co/ar/guides/django-logging)
- [أعدّ سجلات FastAPI وعالج الأخطاء دون فقدان تتبّع المكدّس](https://logbrew.co/ar/guides/fastapi-logging)
- [الفرق بين Trace ID وSpan ID من ترويسة traceparent حقيقية](https://logbrew.co/ar/guides/trace-id)
- [أصلح Minified React error #418 و#185 من الرسالة الكاملة وسطر كودك](https://logbrew.co/ar/errors/minified-react-error)
- [أدلة للأخطاء والسجلات والتتبّعات والمقاييس والإصدارات](https://logbrew.co/ar/guides)
