✅ [19편] 리액트 에러 핸들링 완벽 정리: Error Boundary 사용법과 실무 에러 처리 전략

✅ 리액트 에러 핸들링 완벽 정리: Error Boundary 사용법과 실무 에러 처리 전략

리액트 프로젝트가 커지면 다양한 에러 상황을 마주하게 됩니다.
네트워크 실패, 잘못된 props 전달, 비동기 처리 오류, 렌더링 중 발생하는 예외 등 에러의 종류도 다양합니다.
이런 에러를 방치하면 앱이 갑자기 흰 화면이 되는 “화이트 스크린(White Screen of Death)” 문제가 발생할 수 있습니다.
사용자 경험이 크게 저하되고, 신뢰도에서도 치명적입니다.

리액트에는 이러한 문제를 해결하기 위한 강력한 기능인 **Error Boundary(에러 경계)**가 존재합니다.
이 글에서는 리액트 에러의 종류, Error Boundary 개념, 실무 적용 패턴, API 에러 처리 전략, 로그 수집 방법까지 한 번에 정리합니다.

🟦 1. 리액트에서 발생하는 에러의 종류

리액트 에러는 크게 두 가지 종류로 나눌 수 있습니다.

✔ 1) 렌더링 중 발생하는 에러 (Rendering Error)

컴포넌트 렌더링 도중 다음 같은 에러가 발생할 수 있습니다.

• undefined 객체를 렌더링하려 할 때
• props가 예상 타입과 다를 때
• 잘못된 연산으로 오류 발생할 때
• 컴포넌트 내부에서 throw 발생

이런 에러는 리액트 렌더링 과정에서 발생하기 때문에 전체 앱이 작동을 멈출 수 있습니다.

✔ 2) 이벤트 핸들러/비동기 로직에서 발생하는 에러 (Runtime Error)

예:

const handleClick = () => { throw new Error("버튼 클릭 에러!"); };

이런 에러는 렌더링이 아닌 이벤트 핸들러에서 발생하기 때문에 Error Boundary로는 잡을 수 없습니다.
따라서 별도의 처리 방식이 필요합니다.

🟦 2. Error Boundary란 무엇인가?

Error Boundary는 특정 컴포넌트 범위에서 발생한 렌더링 에러를 감지하고,
앱 전체가 먹통이 되지 않게 “대체 UI(Fallback UI)”를 보여주는 기능입니다.

쉽게 말해,

🔥 "컴포넌트 렌더링 중 에러가 발생하면 해당 컴포넌트만 격리해 안전하게 앱을 유지하는 기술"

이라고 이해할 수 있습니다.

🟦 3. Error Boundary가 처리할 수 있는 것과 처리할 수 없는 것

✔ Error Boundary로 가능한 에러

• 렌더링 에러
• 라이프사이클 에러
• 자식 컴포넌트 트리 내부 에러
• 컴포넌트 초기화 중 발생한 예외

❌ Error Boundary로 불가능한 에러

• 이벤트 핸들러 내부 에러
• 비동기 API 오류
• setTimeout 내부 오류
• 서버 API 응답 오류
• Error Boundary 외부에서 발생한 에러
• SSR(서버 렌더링) 오류

따라서 Error Boundary는 만능이 아니며, 에러 처리 전략은 상황에 맞게 병행해야 합니다.

🟦 4. Error Boundary 기본 사용법

Error Boundary는 클래스형 컴포넌트로만 구현할 수 있습니다.
함수형 컴포넌트에서는 직접 만들 수 없고 외부 라이브러리를 활용해야 합니다.

🔷 4-1. 기본 구현 코드

 

class ErrorBoundary extends React.Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { return { hasError: true }; } componentDidCatch(error, info) { console.log("에러 로그:", error, info); } render() { if (this.state.hasError) { return <h2>문제가 발생했습니다. 잠시 후 다시 시도해주세요.</h2>; } return this.props.children; } }

 

🔷 4-2. 적용 방법

 

<ErrorBoundary> <UserProfile /> </ErrorBoundary>

UserProfile 컴포넌트에서 오류가 발생하면 전체 앱이 멈추지 않고 에러 대체 UI만 표시됩니다.

🟦 5. Error Boundary를 실제 프로젝트에 적용하는 위치

Error Boundary는 어디에 두는지에 따라 효과가 완전히 달라집니다.

✔ 1) 컴포넌트 단위로 작게 적용

예: 특정 기능에서만 에러가 발생할 수 있는 경우

 

<ErrorBoundary> <CommentList /> </ErrorBoundary>

문제 발생 시 댓글만 멈추고 사이트는 정상 유지됩니다.

✔ 2) 페이지 단위에서 감싸기

Next.js, React Router 사용 시

 

<Route path="/dashboard" element={ <ErrorBoundary> <DashboardPage /> </ErrorBoundary> } />

 

✔ 3) 앱 전체를 감싸는 최상위 Error Boundary

App.js 또는 root 레벨에서 적용하면 전역 보호 기능을 합니다.

 

<ErrorBoundary> <App /> </ErrorBoundary>

 

✔ 실무 추천 구조

 

src/ ├ index.js (전역 ErrorBoundary) ├ pages/ │ └ SomePage.js (페이지 단위 ErrorBoundary) ├ components/ │ └ Widget.js (특정 기능용 ErrorBoundary)

이 구조가 가장 안정적입니다.

🟦 6. React 18 이후 Error Boundary 개선점

React 18부터 에러 처리는 다음과 같은 개선 사항을 제공합니다.

• Strict Mode에서 개발 시 에러 감지 강화
• Suspense와 연계해 fallback UI 개선
• 서버 컴포넌트 에러 핸들링 별도 지원

특히 Suspense와 Error Boundary를 함께 사용하면
로딩/에러 처리를 UI 레벨에서 매우 깔끔하게 구성할 수 있습니다.

🟦 7. 이벤트 핸들러/비동기 에러 처리 (Error Boundary가 못 잡는 영역)

앞서 말했듯 Error Boundary는 다음 같은 에러는 잡을 수 없습니다.

• 클릭 이벤트 오류
• API 호출 오류
• 비동기 작업 오류

이 경우 try/catch로 개별적으로 처리해야 합니다.

✔ 7-1. 이벤트 핸들러에서의 에러 처리

 

const handleClick = () => { try { riskyFunction(); } catch (e) { alert("클릭 중 문제가 발생했습니다."); } };

✔ 7-2. API 요청 에러 처리

 

try { const res = await fetch("/api/data"); if (!res.ok) throw new Error("서버 오류"); } catch (error) { setError("데이터를 불러올 수 없습니다."); }

API 오류는 Error Boundary가 감지할 수 없으므로 반드시 비동기 코드 내부에서 처리해야 합니다.

🟦 8. 에러 로깅(Log) 시스템 연동하기

실무에서는 단순히 에러를 잡는 것이 아니라,
에러가 언제, 어디서, 왜 발생했는지 추적하는 “로그 시스템”이 필수입니다.

✔ 추천 로깅 서비스

• Sentry
• LogRocket
• Firebase Crashlytics
• Datadog

Error Boundary의 componentDidCatch 내부에서 에러를 로깅 서버로 전송하는 패턴이 일반적입니다.

 

componentDidCatch(error, info) { sendLogToServer(error, info); }

이렇게 하면 실제 사용자 환경에서 발생한 에러를 실시간으로 추적할 수 있습니다.

🟦 9. 실무에서 가장 많이 쓰는 Error Boundary 설계 패턴

✔ (1) 기능 단위 Error Boundary

특정 위젯이나 리스트에서 오류가 날 가능성이 있을 때

✔ (2) 페이지 단위 Error Boundary

React Router 또는 Next.js에서 route 단위 적용

✔ (3) 전역 Error Boundary + 로깅 시스템

전체 서비스 안정성을 위한 최종 방어선

✔ (4) Suspense + ErrorBoundary 조합

로딩/에러 UI 일관성 확보

🟦 결론: 안정적인 리액트 앱을 위해 Error Boundary는 필수 도구

리액트는 매우 유연하고 강력한 UI 라이브러리이지만, 렌더링 중 발생하는 에러에 취약합니다.
그 어느 한 부분에서라도 오류가 발생하면 사용자에게는 빈 화면이 보일 수 있습니다.

Error Boundary를 잘 활용하면

• 특정 컴포넌트 에러만 격리
• 전체 앱 정상 유지
• 사용자 경험 보호
• 에러를 기록하고 추적
• 안정성 높은 서비스 운영

을 모두 한 번에 달성할 수 있습니다.

리액트 실무에서 Error Boundary는 선택이 아니라 제약 없는 “필수 메커니즘”입니다.