디바이스에서 실행하기

앱을 사용자에게 출시하기 전에 실제 기기에서 테스트하는 것은 항상 좋은 생각이다. 이 문서는 React Native 앱을 기기에서 실행하고 프로덕션 준비를 하는 데 필요한 단계를 안내한다.

info

프로젝트 설정에 create-expo-app을 사용했다면, npm start를 실행할 때 표시되는 QR 코드를 스캔하여 Expo Go에서 앱을 실행할 수 있다. 자세한 내용은 기기에서 프로젝트 실행하기 Expo 가이드를 참고한다.

Android

안드로이드 기기에서 앱 실행하기

개발 운영체제

macOS

1. USB 디버깅 활성화

대부분의 안드로이드 디바이스는 기본적으로 Google Play에서 다운로드한 앱만 설치하고 실행할 수 있다. 개발 중에 앱을 설치하려면 디바이스에서 USB 디버깅을 활성화해야 한다.

디바이스에서 USB 디버깅을 활성화하려면 먼저 설정 → 휴대전화 정보 → 소프트웨어 정보로 이동한 후, 하단의 빌드 번호를 7번 탭하여 "개발자 옵션" 메뉴를 활성화해야 한다. 그런 다음 설정 → 개발자 옵션으로 돌아가 "USB 디버깅"을 활성화하면 된다.

2. USB로 기기 연결하기

이제 React Native 프로젝트를 실행할 Android 기기를 설정해 보자. 개발 머신에 USB 케이블로 기기를 연결한다.

adb devices 명령어를 실행해 Android Debug Bridge(ADB)에 기기가 제대로 연결되었는지 확인한다.

shell

$ adb devices
List of devices attached
emulator-5554 offline   # Google 에뮬레이터
14ed2fcc device         # 실제 기기

오른쪽 컬럼에 device가 표시되면 기기가 정상적으로 연결된 것이다. 한 번에 하나의 기기만 연결해야 한다.

note

목록에 unauthorized가 표시되면 adb reverse tcp:8081 tcp:8081 명령어를 실행하고 기기에서 USB 디버깅 허용을 선택해야 한다.

3. 앱 실행하기

프로젝트 루트 디렉토리에서 다음 커맨드를 입력해 디바이스에 앱을 설치하고 실행한다.

npm

shell

npm run android

Yarn

shell

yarn android

"bridge configuration isn't available" 오류가 발생하면 adb reverse 사용하기를 참고한다.

팁: React Native CLI를 사용해 release 빌드를 생성하고 실행할 수도 있다 (예: 프로젝트 루트에서 yarn android --mode release 실행).

개발 서버에 연결하기

개발 머신에서 실행 중인 개발 서버에 연결해 디바이스에서 빠르게 작업을 반복할 수 있다. USB 케이블이나 Wi-Fi 네트워크 접근 여부에 따라 여러 방법으로 연결할 수 있다.

방법 1: adb reverse 사용 (권장)

이 방법은 기기가 Android 5.0 (Lollipop) 이상 버전에서 실행 중이고, USB 디버깅이 활성화되어 있으며, 개발 머신에 USB로 연결된 경우에 사용할 수 있다.

커맨드라인에서 다음 명령을 실행한다:

shell

$ adb -s <기기 이름> reverse tcp:8081 tcp:8081

기기 이름을 확인하려면 다음 adb 명령을 실행한다:

shell

$ adb devices

이제 개발자 메뉴에서 Fast Refresh를 활성화할 수 있다. 자바스크립트 코드가 변경될 때마다 앱이 자동으로 리로드된다.

방법 2: Wi-Fi를 통해 연결하기

개발 서버에 Wi-Fi로 연결할 수도 있다. 먼저 USB 케이블을 사용해 기기에 앱을 설치해야 하지만, 설치가 완료되면 다음 지침에 따라 무선으로 디버깅할 수 있다. 진행하기 전에 개발 머신의 현재 IP 주소가 필요하다.

IP 주소는 시스템 설정(또는 시스템 환경설정) → 네트워크에서 확인할 수 있다.

1. 노트북과 휴대폰이 동일한 Wi-Fi 네트워크에 연결되어 있는지 확인한다.
2. 기기에서 React Native 앱을 실행한다.
3. 오류가 표시된 빨간 화면이 나타날 수 있다. 이는 정상이며, 다음 단계에서 해결할 수 있다.
4. 앱 내 개발자 메뉴를 연다.
5. 개발자 설정 → 디버그 서버 호스트 및 포트로 이동한다.
6. 개발 머신의 IP 주소와 로컬 개발 서버의 포트를 입력한다(예: 10.0.1.1:8081).
7. 개발자 메뉴로 돌아가 JS 다시 로드를 선택한다.

이제 개발자 메뉴에서 Fast Refresh를 활성화할 수 있다. JavaScript 코드가 변경될 때마다 앱이 자동으로 리로드된다.

프로덕션 환경을 위한 앱 빌드

React Native를 사용해 멋진 앱을 만들었고, 이제 Play Store에 출시하고 싶을 것이다. 이 과정은 다른 네이티브 Android 앱과 동일하지만, 몇 가지 추가 고려 사항이 있다. 자세한 내용은 서명된 APK 생성 가이드를 참고한다.

Windows

1. USB 디버깅 활성화

대부분의 안드로이드 기기는 기본적으로 Google Play에서 다운로드한 앱만 설치하고 실행할 수 있다. 개발 중에 직접 만든 앱을 설치하려면 기기에서 USB 디버깅을 활성화해야 한다.

기기에서 USB 디버깅을 활성화하려면 먼저 설정 → 휴대전화 정보 → 소프트웨어 정보로 이동한 후, 하단의 빌드 번호를 7번 연속으로 탭하여 "개발자 옵션" 메뉴를 활성화해야 한다. 그런 다음 설정 → 개발자 옵션으로 돌아가 "USB 디버깅"을 활성화하면 된다.

2. USB로 기기 연결하기

이제 React Native 프로젝트를 실행할 Android 기기를 설정해 보자. 개발 머신에 USB 케이블을 사용해 기기를 연결한다.

기기가 ADB(Android Debug Bridge)에 제대로 연결되었는지 확인하려면 adb devices 명령어를 실행한다.

shell

$ adb devices
List of devices attached
emulator-5554 offline   # Google 에뮬레이터
14ed2fcc device         # 물리적 기기

오른쪽 컬럼에 device가 표시되면 기기가 연결된 상태다. 이때 한 번에 하나의 기기만 연결되어 있어야 한다.

3. 앱 실행하기

프로젝트 루트 디렉토리에서 다음 커맨드를 실행해 앱을 설치하고 디바이스에서 실행한다:

npm

shell

npm run android

Yarn

shell

yarn android

팁: React Native CLI를 사용해 릴리스 빌드를 생성하고 실행할 수도 있다 (예: 프로젝트 루트에서 yarn android --mode release 실행).

개발 서버에 연결하기

개발 머신에서 실행 중인 개발 서버에 연결해 디바이스에서 빠르게 반복 작업을 진행할 수 있다. USB 케이블이나 Wi-Fi 네트워크 접근 여부에 따라 여러 방법으로 연결할 수 있다.

방법 1: adb reverse 사용 (권장)

이 방법은 안드로이드 5.0 (Lollipop) 이상 버전에서 사용할 수 있다. USB 디버깅이 활성화되어 있고, 개발 머신과 USB로 연결된 상태여야 한다.

커맨드라인에서 다음 명령어를 실행한다:

shell

$ adb -s <device name> reverse tcp:8081 tcp:8081

디바이스 이름을 확인하려면 다음 adb 명령어를 실행한다:

shell

$ adb devices

이제 개발자 메뉴에서 Fast Refresh를 활성화할 수 있다. 자바스크립트 코드가 변경될 때마다 앱이 자동으로 리로드된다.

방법 2: Wi-Fi를 통해 연결하기

개발 서버에 Wi-Fi를 통해 연결할 수도 있다. 먼저 USB 케이블을 사용해 디바이스에 앱을 설치해야 하지만, 한 번 설치가 완료되면 무선으로 디버깅할 수 있다. 다음 단계를 따르기 전에 개발 머신의 현재 IP 주소가 필요하다.

명령 프롬프트를 열고 ipconfig를 입력해 머신의 IP 주소를 확인한다(자세한 정보).

1. 노트북과 휴대폰이 동일한 Wi-Fi 네트워크에 연결되어 있는지 확인한다.
2. 디바이스에서 React Native 앱을 실행한다.
3. 에러와 함께 빨간 화면이 나타날 수 있다. 이는 정상이다. 다음 단계를 통해 해결할 수 있다.
4. 앱 내 개발자 메뉴를 연다.
5. 개발자 설정 → 디바이스용 디버그 서버 호스트 및 포트로 이동한다.
6. 머신의 IP 주소와 로컬 개발 서버의 포트를 입력한다(예: 10.0.1.1:8081).
7. 개발자 메뉴로 돌아가 JS 다시 로드를 선택한다.

이제 개발자 메뉴에서 Fast Refresh를 활성화할 수 있다. JavaScript 코드가 변경될 때마다 앱이 자동으로 리로드된다.

프로덕션 환경을 위한 앱 빌드

React Native를 사용해 멋진 앱을 만들었고, 이제 Play Store에 출시하고 싶을 것이다. 이 과정은 다른 네이티브 Android 앱과 동일하지만, 몇 가지 추가로 고려해야 할 사항이 있다. 자세한 내용은 서명된 APK 생성 가이드를 참고한다.

1. USB를 통한 디버깅 활성화

대부분의 안드로이드 기기는 기본적으로 Google Play에서 다운로드한 앱만 설치하고 실행할 수 있다. 개발 중에 내 앱을 설치하려면 기기에서 USB 디버깅을 활성화해야 한다.

기기에서 USB 디버깅을 활성화하려면 먼저 설정 → 휴대전화 정보 → 소프트웨어 정보로 이동한 후 하단의 빌드 번호 행을 7번 연속으로 탭하여 "개발자 옵션" 메뉴를 활성화해야 한다. 그런 다음 설정 → 개발자 옵션으로 돌아가 "USB 디버깅"을 활성화하면 된다.

2. USB로 기기 연결하기

이제 React Native 프로젝트를 실행할 안드로이드 기기를 설정해 보자. 개발 머신에 USB 케이블로 기기를 연결한다.

다음으로 lsusb 명령어를 사용해 제조사 코드를 확인한다. (맥에서는 먼저 lsusb를 설치해야 한다.) lsusb는 다음과 같은 결과를 출력한다:

bash

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

이 출력 결과는 현재 머신에 연결된 USB 기기들을 나타낸다.

여기서 핸드폰에 해당하는 줄을 찾아야 한다. 만약 확실하지 않다면, 핸드폰을 분리한 후 명령어를 다시 실행해 보자:

bash

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

핸드폰을 분리하면, 핸드폰 모델("Motorola PCS")이 포함된 줄이 목록에서 사라진 것을 확인할 수 있다. 이 줄이 우리가 찾는 것이다.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

위 줄에서 디바이스 ID의 처음 네 자리를 추출한다:

22b8:2e76

이 경우에는 22b8이다. 이 값이 Motorola의 식별자이다.

이 값을 udev 규칙에 입력해 설정을 완료한다:

shell

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

여기서 22b8을 위 명령어에서 얻은 식별자로 바꿔야 한다.

이제 Android Debug Bridge(ADB)에 기기가 제대로 연결되었는지 확인한다. adb devices 명령어를 실행한다.

shell

$ adb devices
List of devices attached
emulator-5554 offline   # Google 에뮬레이터
14ed2fcc device         # 물리적 기기

오른쪽 열에 device가 표시되면 기기가 연결된 것이다. 한 번에 하나의 기기만 연결되어 있어야 한다.

프로젝트 루트 디렉터리에서 다음 커맨드를 입력해 앱을 설치하고 기기에서 실행한다:

npm

shell

npm run android

Yarn

shell

yarn android

"bridge configuration isn't available" 오류가 발생하면 Using adb reverse를 참고한다.

팁: React Native CLI를 사용해 release 빌드를 생성하고 실행할 수도 있다 (예: 프로젝트 루트에서 yarn android --mode release).

개발 서버에 연결하기

개발 머신에서 실행 중인 개발 서버에 연결해 기기에서 빠르게 반복 작업을 진행할 수 있다. USB 케이블 또는 Wi-Fi 네트워크 접근 가능 여부에 따라 여러 방법이 있다.

방법 1: adb reverse 사용 (권장)

이 방법은 기기가 Android 5.0 (Lollipop) 이상 버전에서 실행 중이고, USB 디버깅이 활성화되어 있으며, 개발 머신에 USB로 연결된 경우에 사용할 수 있다.

커맨드라인에서 다음 명령을 실행한다:

shell

$ adb -s <device name> reverse tcp:8081 tcp:8081

기기 이름을 확인하려면 다음 adb 명령을 실행한다:

shell

$ adb devices

이제 개발자 메뉴에서 Fast Refresh를 활성화할 수 있다. JavaScript 코드가 변경될 때마다 앱이 자동으로 리로드된다.

방법 2: Wi-Fi를 통해 연결하기

개발 서버에 Wi-Fi로 연결할 수도 있다. 먼저 USB 케이블을 사용해 기기에 앱을 설치해야 하지만, 한 번 설치한 후에는 다음 지침을 따라 무선으로 디버깅할 수 있다. 진행하기 전에 개발 머신의 현재 IP 주소가 필요하다.

터미널을 열고 /sbin/ifconfig를 입력해 머신의 IP 주소를 확인한다.

1. 노트북과 휴대폰이 동일한 Wi-Fi 네트워크에 연결되어 있는지 확인한다.
2. 기기에서 React Native 앱을 연다.
3. 오류가 있는 빨간 화면이 나타날 수 있다. 이는 정상이다. 다음 단계에서 이를 해결할 수 있다.
4. 앱 내 개발자 메뉴를 연다.
5. 개발 설정 → 디버그 서버 호스트 및 포트로 이동한다.
6. 머신의 IP 주소와 로컬 개발 서버의 포트를 입력한다 (예: 10.0.1.1:8081).
7. 개발자 메뉴로 돌아가 JS 다시 로드를 선택한다.

이제 개발자 메뉴에서 Fast Refresh를 활성화할 수 있다. JavaScript 코드가 변경될 때마다 앱이 자동으로 리로드된다.

프로덕션 환경을 위한 앱 빌드

React Native로 멋진 앱을 만들었고, 이제 Play Store에 출시하고 싶을 것이다. 이 과정은 일반 네이티브 Android 앱과 동일하지만, 몇 가지 추가 고려 사항이 있다. 자세한 내용은 서명된 APK 생성 가이드를 참고한다.

iOS

iOS 기기에서 앱 실행하기

개발 OS

macOS

1. USB 케이블로 기기 연결하기

아이폰이나 아이패드를 USB to Lightning 또는 USB-C 케이블로 맥에 연결한다. 프로젝트 폴더에서 ios 폴더로 이동한 후, .xcodeproj 파일을 연다. 만약 CocoaPods를 사용한다면 .xcworkspace 파일을 Xcode로 열면 된다.

만약 처음으로 iOS 기기에서 앱을 실행한다면, 개발용으로 기기를 등록해야 할 수 있다. Xcode 메뉴바에서 Product 메뉴를 열고, Destination으로 이동한다. 목록에서 연결한 기기를 찾아 선택하면 Xcode가 자동으로 개발용 기기로 등록한다.

2. 코드 서명 설정하기

아직 Apple 개발자 계정이 없다면 먼저 등록한다.

Xcode 프로젝트 네비게이터에서 프로젝트를 선택한 후, 메인 타겟을 선택한다(프로젝트와 동일한 이름을 가진 타겟). "General" 탭으로 이동한다. "Signing" 섹션에서 Apple 개발자 계정이나 팀이 Team 드롭다운에 선택되어 있는지 확인한다. 테스트 타겟(이름이 Tests로 끝나며 메인 타겟 아래에 위치)에 대해서도 동일한 작업을 반복한다.

프로젝트 내 Tests 타겟에 대해 이 단계를 반복한다.

3. 앱 빌드 및 실행

모든 설정이 올바르게 완료되면, Xcode 툴바에서 기기가 빌드 대상으로 표시된다. 또한 기기가 디바이스 패널(Shift ⇧ + Cmd ⌘ + 2)에 나타난다. 이제 빌드 및 실행 버튼(Cmd ⌘ + R)을 누르거나 Product 메뉴에서 Run을 선택할 수 있다. 잠시 후 앱이 기기에서 실행된다.

문제가 발생하면 Apple의 Launching Your App on a Device 문서를 참고한다.

개발 서버에 연결하기

개발 서버를 사용하면 기기에서 빠르게 반복 작업을 할 수 있다. 컴퓨터와 같은 Wi-Fi 네트워크에 연결하기만 하면 된다. 기기를 흔들어 Dev Menu를 열고, Fast Refresh를 활성화한다. JavaScript 코드가 변경될 때마다 앱이 자동으로 리로드된다.

문제 해결

문제가 발생하면 Mac과 기기가 같은 네트워크에 연결되어 있고 서로 통신할 수 있는지 확인한다. 캡티브 포털이 있는 무선 네트워크는 기기 간 통신을 막도록 설정된 경우가 많다. 이런 경우 기기의 개인 핫스팟 기능을 사용할 수 있다. 또한 Mac의 인터넷 연결(Wi-Fi/이더넷)을 USB를 통해 기기와 공유하고, 이 터널을 통해 번들러에 연결하면 매우 빠른 전송 속도를 얻을 수 있다.

개발 서버에 연결하려고 할 때 다음과 같은 오류 메시지가 있는 빨간색 화면이 나타날 수 있다:

http://localhost:8081/debugger-proxy?role=client에 연결하는 데 시간이 초과되었습니다. 노드 프록시를 실행 중인가요? 기기에서 실행 중이라면 RCTWebSocketExecutor.m 파일에 올바른 IP 주소가 있는지 확인하세요.

이 문제를 해결하려면 다음 사항을 점검한다.

1. Wi-Fi 네트워크

노트북과 휴대폰이 동일한 Wi-Fi 네트워크에 연결되어 있는지 확인한다.

2. IP 주소

빌드 스크립트가 여러분의 머신 IP 주소를 정확히 감지했는지 확인한다(예: 10.0.1.123).

Report navigator 탭을 열고, 마지막 Build를 선택한 후 IP= 뒤에 오는 IP 주소를 검색한다. 앱에 포함된 IP 주소가 여러분의 머신 IP 주소와 일치해야 한다.

앱을 프로덕션 환경으로 빌드하기

React Native를 사용해 멋진 앱을 만들었고, 이제 App Store에 출시하고 싶을 것이다. 이 과정은 다른 네이티브 iOS 앱과 동일하지만, 몇 가지 추가 고려 사항이 있다. 더 자세한 내용은 Apple App Store에 출시하기 가이드를 참고한다.

Windows

iOS 기기용 앱을 빌드하려면 Mac이 필요하다. 또는 환경 설정 가이드를 참고해 Expo CLI를 사용해 앱을 빌드하는 방법을 알아볼 수 있다. 이 방법을 사용하면 Expo 클라이언트 앱을 통해 앱을 실행할 수 있다.

Linux

iOS 기기용 앱을 빌드하려면 Mac이 필요하다. 또는 환경 설정 가이드를 참고해 Expo CLI를 사용해 앱을 빌드하는 방법을 알아볼 수 있다. 이 방법을 사용하면 Expo 클라이언트 앱을 통해 앱을 실행할 수 있다.