개요
내 컴퓨터(Mac/Windows)의 React Native 개발 환경이 정상적으로 갖춰져 있는지 진단하고, 문제점(에러)을 찾아주는 기능이 있다. 바로 react-native doctor다.
React Native CLI에 내장된 개발 환경 진단 도구로, 프로젝트를 빌드하는 데 필요한 의존성들의 설치 상태와 버전을 자동으로 검사하고, 문제가 있으면 일부 항목은 자동 수정까지 해주는 아주 좋은 친구다.
무엇을 진단해줄까?
npx react-native doctor프로젝트 루트 디렉터리에서 위 명령어를 입력하면, 앱 빌드에 필요한 필수 요소들을 싹 검사해서 직관적인 기호로 결과를 알려준다.
✓(녹색) — 정상●(노란색) — 경고 (빌드는 되지만 권장 사양/버전이 아님)✖(빨간색) — 오류 (빌드 실패 가능성 있음)
검사 항목은 아래와 같다.
- 공통 환경 (Common)
Node.js, npm/Yarn, Watchman, Metro 등이 잘 설치되어 있고 권장 버전과 맞는지 확인한다. - Android 환경
Android Studio 설치 여부, Android SDK, JDK(Java) 버전,ANDROID_HOME환경 변수, Adb(연결된 디바이스/에뮬레이터), Gradlew 등이 정확히 잡혀 있는지 검사한다. - iOS 환경 (Mac 전용)
Xcode, CocoaPods 설치 상태와 권한, Ruby 버전, ios-deploy(선택) 등을 확인한다.
자동 치료 기능
doctor는 진단만 하고 끝내지 않는다. 검사가 끝나면 터미널 하단에 다음과 같은 선택지가 나타난다.
Usage
› Press f to try to fix issues.
› Press e to try to fix errors.
› Press w to try to fix warnings.
› Press Enter to exit.f— 발견된 모든 문제(오류+경고) 수정 시도e— 오류(✖)만 수정 시도w— 경고(●)만 수정 시도Enter— 그냥 종료
키를 누르면 doctor가 빠진 Android SDK 컴포넌트를 다운로드하거나, 꼬여버린 CocoaPods를 재설치하는 등 자동으로 환경을 수리해 준다. 수동으로 구글링하며 설치 경로를 찾아다닐 시간을 꽤 아껴주는 기능이다.
다만 doctor가 모든 걸 고쳐주는 건 아니다. 자기가 자동으로 처리하지 못하는 항목(예: Android Studio 설치 자체, JDK 버전·경로 충돌, ANDROID_HOME 잘못 설정 등)은 수정 대신 수동 설치 안내 링크만 띄운다. f를 눌러도 그대로인 경우가 종종 있으니, 자동 수정은 "1차 시도" 정도로 생각하고 안 되면 링크를 따라 직접 손보는 흐름이 현실적이다.
실무에서는 다음과 같은 상황에 주로 사용하면 좋다.
- 새 회사 노트북/데스크탑에서 처음 환경을 세팅할 때
- GitHub에서 남의 프로젝트를 클론(Clone)했는데 내 컴퓨터에서만 빌드가 안 될 때
- macOS·Xcode·Android Studio를 업데이트한 직후 빌드가 갑자기 꼬였을 때
그럼 스펙 명세서만 간단히 보고 싶으면?
react-native doctor는 치료까지 해주지만, 스펙 명세서만 빠르게 보고 싶다면 아래 명령어를 쓰면 된다.
npx react-native info이 명령어는 환경을 진단하거나 고쳐주지는 않는다. 대신 현재 내 환경이 어떤 버전들로 구성되어 있는지 텍스트로 깔끔하게 요약해서 복사하기 좋게 출력해 준다. 출력 목록은 아래와 같다.
- System : 운영체제(macOS/Windows) 버전, CPU 종류(M1/M2/M3, Intel 등), 메모리, 셸
- Binaries : Node.js, Yarn, npm의 정확한 설치 버전
- IDEs : Android Studio, Xcode의 현재 버전
- SDKs : Android SDK, iOS SDK 버전
- npmPackages : 현재 프로젝트에 설치된
react,react-native의 정확한 버전(wanted / installed)
RN 같은 크로스플랫폼 앱 개발은 다른 환경에 비해 패키지 버전 호환이 매우 중요하고 민감하다. 그래서 버전 충돌 에러가 자주 난다. 이때 GitHub에 버그 리포트(Issue)를 올리거나 Stack Overflow·개발자 커뮤니티에 질문할 때, 이 info 결과를 복사해서 붙여넣는 것이 국룰이다.
doctor vs info 한눈에 비교
react-native doctor | react-native info | |
|---|---|---|
| 목적 | 환경 진단 + 자동 수정 | 환경 요약 출력 |
| 결과 형태 | ✓/●/✖ 체크리스트 | 버전 정보 텍스트 |
| 수정 기능 | 있음 (f/e/w) | 없음 |
| 주 용도 | 세팅·트러블슈팅 | 버그 리포트 첨부용 |
