React Native iOS 실기기 테스트, ios-deploy로 빠르게 돌리기

React Native로 iOS를 개발하면서 Xcode를 매번 여는 게 번거로울 때가 있다. 특히 실기기에 올려서 확인만 하고 싶을 때는 더 그렇다.

이때 쓰는 게 ios-deploy다.

https://www.npmjs.com/package/ios-deploy

ios-deploy가 하는 일

Xcode 없이 커맨드라인에서 iOS 기기에 앱을 설치하고 실행하고 디버깅할 수 있게 해주는 도구다. React Native CLI가 내부적으로 run-ios를 실기기에 돌릴 때도 이걸 쓴다.

설치

# Homebrew (권장)
brew install ios-deploy

# npm 전역 설치
npm install -g ios-deploy

Homebrew 쪽을 권한다. npm으로 설치하면 네이티브 빌드가 필요해서 Xcode 커맨드라인 툴 버전에 따라 실패하는 경우가 있다.

기본 사용법

# 연결된 기기 목록 확인
ios-deploy -c

# .app 설치
ios-deploy --bundle ./build/MyApp.app

# 설치 후 바로 실행
ios-deploy --bundle ./build/MyApp.app --justlaunch

# 특정 기기 지정
ios-deploy --id <device-udid> --bundle ./build/MyApp.app

# 설치 후 디버거 붙이고 로그 보기
ios-deploy --debug --bundle ./build/MyApp.app

React Native에서 실기기로 돌리기

실제로는 ios-deploy를 직접 호출하기보다 RN CLI를 쓰는 경우가 많다. 이때 ios-deploy가 설치돼 있어야 동작한다.

# 연결된 기기 목록
xcrun xctrace list devices

# 특정 기기에서 실행
npx react-native run-ios --device "내 아이폰"

# UDID로 지정
npx react-native run-ios --udid 00008030-XXXXXXXXXXXX

--device 옵션을 쓸 때 ios-deploy가 없으면 RN CLI가 설치하라는 에러를 낸다. 이 글의 도구가 필요한 지점이 바로 여기다.

자주 막히는 지점

1. 서명(Signing) 문제

ios-deploy는 이미 서명된 .app을 설치하는 도구다. 서명 자체를 대신해주지는 않는다. 처음 한 번은 Xcode에서 Signing & Capabilities 설정을 해줘야 한다.

• Xcode > 프로젝트 > Signing & Capabilities
• Team 선택 (무료 Apple ID도 가능)
• Bundle Identifier를 고유한 값으로 변경

무료 계정으로 서명하면 7일 후 앱이 만료된다. 테스트 주기가 길면 유료 개발자 계정이 필요하다.

2. 기기 신뢰 설정

설치는 됐는데 실행하면 "신뢰할 수 없는 개발자" 경고가 뜨는 경우다.

설정 > 일반 > VPN 및 기기 관리 > 개발자 앱 > 신뢰

3. 기기가 목록에 안 나올 때

• 케이블이 데이터 전송용인지 확인 (충전 전용 케이블이 의외로 많다)
• 기기에서 "이 컴퓨터를 신뢰하시겠습니까?" 팝업에 신뢰 선택
• iOS 16 이상은 개발자 모드를 켜야 한다: 설정 > 개인정보 보호 및 보안 > 개발자 모드

마지막 항목이 iOS 16부터 생긴 것이라 예전 자료만 보고 있으면 한참 헤맨다.

4. 무선으로 연결하고 싶다면

ios-deploy --detect --timeout 5

# Xcode에서 한 번 무선 연결을 설정해두면
# Window > Devices and Simulators > Connect via network

요즘은 다른 선택지도 있다

ios-deploy는 여전히 유효하지만, 팀 단위로 배포를 돌린다면 다른 도구를 같이 보는 게 좋다.

• Expo Dev Client: RN을 Expo 기반으로 쓰면 QR 코드로 배포된다. 네이티브 모듈이 필요해도 dev client를 한 번 빌드해두면 이후 JS 변경은 무선으로 반영된다.
• TestFlight: 실제 테스터에게 배포한다면 결국 이쪽이다. 심사가 필요하지만 내부 테스터는 즉시 배포된다.
• EAS Build / Fastlane: 빌드와 서명을 CI에서 처리한다. 로컬 Xcode 설정 문제에서 해방된다.

혼자 빠르게 확인할 때는 ios-deploy가 여전히 가장 가볍다. 케이블 꽂고 명령 한 줄이면 끝이라는 게 장점이다.

정리

• brew install ios-deploy 로 설치 (npm보다 안정적)
• ios-deploy -c 로 기기 확인, --bundle 로 설치
• RN에서는 npx react-native run-ios --device 가 내부적으로 이걸 쓴다
• 서명은 별도다. 처음 한 번은 Xcode 설정 필요
• iOS 16+ 는 개발자 모드를 켜야 기기가 잡힌다
• 무료 서명은 7일 만료