Skip to main content
Version: Next

문제 해결

React Native를 설정하는 동안 발생할 수 있는 일반적인 문제들을 소개한다. 여기 나열되지 않은 문제가 발생한다면, GitHub에서 해당 이슈를 검색해 보는 것이 좋다.

포트가 이미 사용 중일 때​

Metro 번들러는 기본적으로 8081 포트에서 실행된다. 만약 다른 프로세스가 이미 해당 포트를 사용 중이라면, 해당 프로세스를 종료하거나 번들러가 사용하는 포트를 변경할 수 있다.

8081 포트에서 실행 중인 프로세스 종료하기​

8081 포트를 사용 중인 프로세스의 ID를 찾으려면 다음 커맨드를 실행한다:

shell
sudo lsof -i :8081

그런 다음 해당 프로세스를 종료하려면 다음 커맨드를 실행한다:

shell
kill -9 <PID>

윈도우에서는 리소스 모니터를 사용해 8081 포트를 사용 중인 프로세스를 찾고, 작업 관리자를 통해 종료할 수 있다.

8081 이외의 포트 사용하기​

프로젝트 루트에서 port 파라미터를 사용해 번들러가 8081 이외의 포트를 사용하도록 설정할 수 있다. 아래 명령어를 실행하면 된다:

shell
npm start -- --port=8088

또한, 애플리케이션에서 새로운 포트로부터 JavaScript 번들을 로드하도록 업데이트해야 한다. Xcode에서 디바이스로 실행 중이라면, ios/__App_Name__.xcodeproj/project.pbxproj 파일에서 8081을 선택한 포트로 변경하면 된다.

NPM 잠금 오류 해결​

React Native CLI를 사용하다가 npm WARN locking Error: EACCES와 같은 오류가 발생한다면, 다음 명령어를 실행해 보세요.

shell
sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

React 라이브러리 누락 문제 해결​

프로젝트에 React Native를 수동으로 추가한 경우, RCTText.xcodeproj, RCTImage.xcodeproj와 같이 사용 중인 모든 관련 의존성을 포함했는지 확인한다. 다음으로, 이러한 의존성으로 빌드된 바이너리가 앱 바이너리와 연결되어야 한다. Xcode 프로젝트 설정에서 Linked Frameworks and Binaries 섹션을 사용한다. 더 자세한 단계는 링크 라이브러리에서 확인할 수 있다.

CocoaPods를 사용하는 경우, Podfile에 React와 서브스펙을 추가했는지 확인한다. 예를 들어, <Text />, <Image />, fetch() API를 사용한다면 Podfile에 다음과 같이 추가해야 한다:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
  'RCTText',
  'RCTImage',
  'RCTNetwork',
  'RCTWebSocket',
]

그런 다음, pod install을 실행하고 프로젝트에 Pods/ 디렉토리가 생성되었는지, React가 설치되었는지 확인한다. CocoaPods는 이후부터 생성된 .xcworkspace 파일을 사용하도록 안내할 것이다. 이 파일을 사용하면 설치된 의존성을 활용할 수 있다.

React Native를 CocoaPod으로 사용할 때 컴파일되지 않는 문제​

CocoaPods 플러그인 중 하나인 cocoapods-fix-react-native는 의존성 관리자를 사용할 때 발생할 수 있는 소스 코드의 차이점을 해결하기 위해 사후 수정 작업을 처리한다.

인수 목록이 너무 김: 재귀적 헤더 확장 실패​

프로젝트 빌드 설정에서 User Search Header Paths와 Header Search Paths는 코드에 지정된 #import 헤더 파일을 찾을 위치를 지정하는 두 가지 설정이다. Pods의 경우, CocoaPods는 특정 폴더 배열을 기본값으로 사용하여 헤더 파일을 찾는다. 이 설정이 덮어쓰여지지 않았는지, 그리고 설정된 폴더 중 너무 큰 폴더가 없는지 확인해야 한다. 만약 폴더 중 하나가 큰 폴더라면, Xcode는 전체 디렉토리를 재귀적으로 검색하려고 시도하다가 어느 시점에서 위와 같은 오류를 발생시킨다.

User Search Header Paths와 Header Search Paths 빌드 설정을 CocoaPods가 설정한 기본값으로 되돌리려면, Build Settings 패널에서 해당 항목을 선택하고 삭제 버튼을 누른다. 이렇게 하면 커스텀 오버라이드가 제거되고 CocoaPod의 기본값으로 돌아간다.

사용 가능한 전송 프로토콜이 없음​

React Native는 WebSockets을 위한 폴리필을 구현한다. 이 폴리필은 애플리케이션에서 import React from 'react'를 통해 포함하는 react-native 모듈의 일부로 초기화된다. Firebase와 같이 WebSockets이 필요한 다른 모듈을 로드할 때는 반드시 react-native 이후에 로드해야 한다:

import React from 'react';
import Firebase from 'firebase';

셸 명령 응답 없음 예외​

ShellCommandUnresponsiveException 예외가 발생하는 경우, 예를 들어 다음과 같은 오류 메시지가 표시되면:

Execution failed for task ':app:installDebug'.
  com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

android/build.gradle 파일에서 Gradle 버전을 1.2.3으로 다운그레이드해 보세요. 자세한 내용은 이 GitHub 이슈를 참고하세요.

react-native init 명령어가 멈출 때​

npx react-native init 명령어를 실행할 때 시스템에서 멈추는 문제가 발생한다면, verbose 모드로 다시 실행해 보세요. 또한 일반적인 원인에 대한 정보는 #2797 이슈를 참고하세요.

shell
npx react-native init --verbose

프로세스를 디버깅하거나 발생한 오류에 대해 더 자세히 알아야 할 때는 verbose 옵션을 사용해 더 많은 로그와 정보를 출력해 문제를 정확히 파악할 수 있습니다.

프로젝트의 루트 디렉터리에서 다음 명령어를 실행하세요.

shell
npm run android -- --verbose

리액트 네이티브 패키지 매니저 시작 오류 (Linux 환경)​

사례 1: "code":"ENOSPC","errno":"ENOSPC" 오류 발생​

이 문제는 Linux에서 watchman이 사용하는 inotify가 모니터링할 수 있는 디렉토리 수가 제한되어 발생한다. 이를 해결하려면 터미널에서 다음 명령어를 실행한다.

shell
echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

macOS에서 npm run android 또는 yarn android를 실행할 때 위와 같은 에러가 발생한다면, sudo chmod +x android/gradlew 명령어를 실행하여 gradlew 파일을 실행 가능한 상태로 만들어야 한다.