React Native 빌드 에러, 흔한 것부터 잡기

핵심 요약

RN 빌드 에러의 상당수는 코드가 아니라 캐시·네이티브 의존성 불일치다. 메트로 캐시, node_modules, iOS Pods, Android Gradle 캐시를 순서대로 초기화하면 "어제는 됐는데" 류 에러가 대부분 풀린다.

1. 클린 순서

watchman watch-del-all
rm -rf node_modules && npm install
npm start -- --reset-cache          # 메트로 캐시
# iOS
cd ios && pod install && cd ..
# Android
cd android && ./gradlew clean && cd ..

2. 자주 보는 에러

에러	원인
Unable to resolve module	메트로 캐시/경로 → reset-cache
Pod 관련 실패	pod install 누락/버전
duplicate symbols	네이티브 모듈 중복 링크

3. 함정

네이티브 모듈 추가 후 pod install·재빌드 없이 JS만 리로드하면 실패
RN/네이티브 SDK 버전 불일치 — 업그레이드 가이드 확인
iOS는 시뮬레이터/실기기 아키텍처 차이 주의

자주 묻는 질문

코드를 안 바꿨는데 갑자기 빌드가 깨져요.

대개 캐시·네이티브 의존성 문제입니다. 메트로 reset-cache, pod install, gradlew clean을 순서대로 하면 많이 해결됩니다.

네이티브 모듈을 깔았는데 못 찾는대요.

JS 리로드만으론 네이티브가 링크되지 않습니다. iOS는 pod install, 양 플랫폼 모두 앱을 새로 빌드해야 합니다.