Theo dõi lỗi cho app React

Trả lời nhanh#

• Cài @belvador/react, gọi init với DSN của bạn và bọc app trong ErrorBoundary.

• Gói báo lỗi render kèm component stack, lỗi root của React 19 và lỗi chưa xử lý trên trình duyệt.

• Event được lọc dữ liệu nhạy cảm trên trình duyệt và lọc lần nữa trên node trong project Hetzner của bạn.

• Nếu đang dùng @sentry/react, bạn đổi dòng import và DSN.

Bắt được những gì#

• Lỗi render qua ErrorBoundary, kèm component stack, trong khi fallback của bạn thay cho trang trắng.

• Lỗi root của React 19 — onUncaughtError, onCaughtError và onRecoverableError qua reactErrorHandler(). React 19 tự xử lý nhiều lỗi, nên thiếu các hook này thì lỗi không bao giờ tới window.onerror.

• Lỗi và promise rejection chưa xử lý sau khi init chạy.

• Stack trace trỏ về mã nguồn khi bạn upload source map từ CI (source map).

Mặc định không gửi: breadcrumb, tệp đính kèm và trace header phải bật thủ công, và không có replay hay tracing trên trình duyệt (khả năng hỗ trợ).

Cài đặt#

npm install @belvador/react@0.6.1

Khởi tạo (React 18 và 19)#

import { init } from "@belvador/react";init({  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",  release: import.meta.env.VITE_APP_VERSION, // your build or commit id  environment: import.meta.env.MODE,});

Import file đó ở dòng đầu tiên của src/main.tsx, trước App, để một module lỗi lúc đang nạp vẫn được báo:

import "./instrument"; // first line: starts Belvador before App's modules loadimport { createRoot } from "react-dom/client";import { ErrorBoundary } from "@belvador/react";import App from "./App";const root = document.getElementById("root");if (!root) throw new Error("Root element missing");createRoot(root).render(  <ErrorBoundary fallback={<p>Something went wrong.</p>}>    <App />  </ErrorBoundary>,);

Với React 19, truyền thêm reactErrorHandler() vào tuỳ chọn của root; hướng dẫn React có cả hai phiên bản và dòng Content Security Policy cần thêm.

Kiểm tra đã chạy#

Gọi verifyIntegration() một lần từ production, hoặc ném một lỗi thử có gắn tag, và tab Kết nối của project hiện Đã xác minh cho trình duyệt (kiểm kết nối).

Giới hạn#

• Chỉ trình duyệt. Server render trên Workers thì dùng TanStack Start; server Node.js thì dùng Node.js.

• Next.js chưa có gói Belvador đã kiểm thử.

• Không có session replay và hộp thoại phản hồi người dùng: hộp thoại đó tải script từ host của DSN, điều mà Belvador không bao giờ làm.

Câu hỏi thường gặp#

Tôi đang dùng @sentry/react. Cần đổi gì?#

Đổi import sang @belvador/react và DSN sang DSN Belvador. captureException, withScope, setTag và ErrorBoundary giữ nguyên tên (chuyển từ Sentry).

Gói nặng bao nhiêu?#

Trong bản build phát hành 0.4.0, @belvador/react với init và ErrorBoundary đo được 37,6 KB gzip; @sentry/browser với init mặc định đo được 28,7 KB trong cùng bản build. Tham chiếu SDK liệt kê các gói hiện tại.