리액트 네이티브 0.86 아이오에스 클라우드 빌드

리액트 네이티브 0.86 아이오에스 클라우드 빌드의 승자는 로컬 코딩과 원격 맥 빌드를 나누는 방식입니다. 자바스크립트와 타입스크립트 작성은 윈도우나 리눅스에 남기고, 아이오에스 의존성 설치, 네이티브 디버깅, 보관 파일 생성, 서명과 앱 스토어 커넥트 업로드만 원격 맥에서 처리하는 편이 효율적입니다.

이 글은 다음 독자를 대상으로 합니다.

• 윈도우나 리눅스에서 리액트 네이티브 앱을 작성하지만 로컬 맥이 없는 독립 개발자
• 네이티브 모듈, 엑스코드 프로젝트, 코코아팟을 직접 관리하는 개발자
• 수동으로 한 번 성공한 빌드를 반복 가능한 아이오에스 구축 환경으로 바꾸려는 소규모 팀

마지막 업데이트: 2026년 8월 15일. 리액트 네이티브 공식 버전 페이지, 0.86 릴리스 문서, 환경 설정 문서와 애플 개발자 문서를 기준으로 내용을 다시 확인했습니다. 리액트 네이티브 0.86은 2026년 6월 11일 공개됐으며, 0.87은 2026년 8월 11일 별도 안정 버전으로 공개됐으므로 두 버전의 요구 사항을 섞지 않아야 합니다. (reactnative.dev)

로컬 코딩과 원격 맥 빌드를 먼저 분리합니다

리액트 네이티브 0.86 프로젝트라고 해서 전체 개발 과정을 원격 맥으로 옮길 필요는 없습니다. 화면 코드와 상태 관리, 일반적인 자바스크립트 테스트는 기존 윈도우나 리눅스 환경에서 유지할 수 있습니다.

반면 다음 작업은 맥 영역으로 분리하는 것이 안전합니다.

• 엑스코드 프로젝트와 아이오에스 네이티브 코드 수정
• 코코아팟 의존성 설치와 워크스페이스 생성
• 아이오에스 시뮬레이터 실행
• 실제 기기용 릴리스 보관 파일 생성
• 개발자 인증서, 프로비저닝 프로파일과 권한 설정
• 앱 스토어 커넥트 업로드

공식 환경 문서도 아이오에스 네이티브 코드 빌드에는 맥이 필요하다고 안내합니다. 편집기는 어느 운영체제에서나 사용할 수 있지만, 아이오에스 빌드 도구와 시뮬레이터를 설치하려면 엑스코드가 필요합니다. (reactnative.dev)

프레임워크 사용 여부에 따른 차이

프로젝트가 관리형 프레임워크에만 의존하고 네이티브 설정을 거의 건드리지 않는다면 원격 맥의 사용 빈도는 낮아질 수 있습니다. 그러나 다음 조건에 해당하면 완전한 맥 제어 권한이 필요합니다.

• 사용자 정의 네이티브 모듈이 있습니다.
• 팟 파일에 직접 설정을 추가했습니다.
• 권한, 키체인, 푸시 알림 설정을 변경합니다.
• 엑스코드 빌드 단계나 스킴을 수정합니다.
• 여러 아이오에스 대상이나 확장 기능을 함께 빌드합니다.

이때 웹 화면만 제공되는 제한된 빌드 서비스는 원인 분석에 불리합니다. 터미널 명령, 그래픽 엑스코드 설정, 시뮬레이터 확인을 모두 처리하려면 원격 맥의 전체 사용자 권한과 터미널 접근이 필요합니다.

시작 전에 다음 항목도 저장소와 애플 계정에서 확인해야 합니다.

• 저장소 읽기와 쓰기 권한
• 애플 개발자 계정의 팀 권한
• 앱의 번들 식별자
• 자바스크립트와 아이오에스 잠금 파일
• 테스트, 테스트플라이트, 정식 배포 중 목표
• 기존 인증서와 프로비저닝 프로파일의 관리 주체

첫 한 시간은 최신 버전보다 프로젝트 기준으로 고정합니다

리액트 네이티브 공식 환경 문서는 노드, 감시 도구, 엑스코드, 코코아팟 설치를 안내합니다. 현재 문서에는 노드 22.11.0 이상이 권장되고, 엑스코드와 명령줄 도구, 시뮬레이터 구성도 별도로 확인해야 합니다. 다만 실제 프로젝트의 요구 버전이 우선입니다. (reactnative.dev)

원격 맥에 접속한 뒤 다음 순서로 기준을 기록합니다.

1. 프로젝트에서 요구 버전을 읽습니다

다음 파일을 먼저 확인합니다.

cd ~/작업폴더/프로젝트명

cat package.json
cat .nvmrc 2>/dev/null || true
cat Gemfile 2>/dev/null || true
cat ios/Podfile
cat ios/Podfile.lock 2>/dev/null || true

여기서 확인할 내용은 다음과 같습니다.

• 노드 버전 파일의 존재 여부
• 패키지 관리자와 잠금 파일의 종류
• 루비와 코코아팟 고정 여부
• 팟 저장소와 네이티브 모듈 설정
• 사용자 정의 빌드 스크립트의 경로

명령을 실행한 터미널과 엑스코드의 빌드 환경이 다를 수 있다는 점이 핵심입니다. 공식 문서는 엑스코드 빌드 단계에서 노드 경로를 찾도록 .xcode.env 파일을 활용하는 방법을 안내합니다. (reactnative.dev)

2. 엑스코드와 명령줄 도구를 확인합니다

xcodebuild -version
xcode-select -p
xcrun simctl list devices available | head
node --version
ruby --version
pod --version

출력 예시는 형식만 보여주는 용도입니다.

Xcode 16.x
Build version xxxxx
/Applications/Xcode.app/Contents/Developer
v22.x.x
ruby x.x.x
x.x.x

위의 버전은 고정값으로 복사하지 않아야 합니다. 리액트 네이티브 프로젝트의 잠금 파일과 공식 환경 문서를 기준으로 실제 범위를 정해야 합니다.

활성 개발자 디렉터리가 다른 엑스코드 버전을 가리키면 다음처럼 수정합니다.

sudo xcode-select --switch /Applications/Xcode.app
sudo xcodebuild -runFirstLaunch

그 다음 엑스코드 설정에서 명령줄 도구와 필요한 아이오에스 시뮬레이터를 설치합니다. 시뮬레이터는 사용하려는 아이오에스 대상과 일치해야 합니다.

3. 비대화형 빌드 경로를 고정합니다

대화형 셸에서만 노드가 보이고 엑스코드에서는 보이지 않는 문제가 자주 발생합니다. 다음처럼 프로젝트의 환경 파일을 확인합니다.

cat .xcode.env 2>/dev/null || true
which node
which npm

노드 버전 관리 도구를 사용한다면 셸 초기화 위치도 점검합니다.

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
which node

빌드 스크립트가 개인 계정의 절대 경로나 대화형 입력을 요구하면 원격 환경에서 재현되지 않습니다. 작업 폴더, 노드 경로, 인증 정보의 주입 방식을 문서화해야 합니다.

의존성은 복사하지 말고 잠금 파일로 복원합니다

원격 맥으로 옮길 대상은 소스 코드와 설정 파일입니다. 다음 생성 결과물은 복사하지 않는 것이 좋습니다.

• node_modules
• ios/Pods
• ios/build
• 파생 데이터
• 시뮬레이터 캐시
• 개인 키체인과 임시 서명 파일

이 폴더를 그대로 옮기면 운영체제, 노드 모듈, 루비 환경이 달라졌을 때 오래된 바이너리나 로컬 절대 경로가 남을 수 있습니다.

4. 저장소와 잠금 파일만 내려받습니다

git clone <저장소 주소> ~/작업폴더/프로젝트명
cd ~/작업폴더/프로젝트명

git status
git branch --show-current

명령에 실제 저장소 주소, 팀 식별자, 비밀 키 경로를 넣지 않아야 합니다. 예시는 모두 자리표시자로 유지합니다.

자바스크립트 의존성은 프로젝트의 잠금 파일에 맞춰 복원합니다.

npm ci

또는 프로젝트가 다른 패키지 관리자를 사용한다면 그 도구의 잠금 파일 기반 설치 명령을 사용합니다. 중요한 것은 새 버전을 계산하는 설치가 아니라 저장소에 기록된 의존성 집합을 재현하는 것입니다.

아이오에스 의존성은 프로젝트 문서와 팟 파일의 요구에 따라 설치합니다.

cd ios
pod install
cd ..

팟 설치가 성공해도 릴리스 빌드가 보장되는 것은 아닙니다. 팟 설치는 의존성 해석 단계입니다. 이후 컴파일, 링크, 서명, 권한과 보관 파일 생성이 별도로 통과해야 합니다.

5. 로컬 경로와 환경 변수를 검색합니다

grep -R "/Users/" ios package.json .xcode.env 2>/dev/null || true
grep -R "NODE_BINARY\|TEAM_ID\|BUNDLE" ios package.json .xcode.env 2>/dev/null || true

다음 문제가 있으면 먼저 수정합니다.

• 특정 개발자의 홈 폴더를 가리키는 경로
• 로컬에서만 존재하는 스크립트
• 숨겨진 환경 변수
• 대화형 셸에서만 설정되는 노드 경로
• 저장소에 포함되지 않은 인증서 파일

실패 지점을 나누려면 로그를 단계별로 저장합니다.

npx react-native doctor 2>&1 | tee ~/로그/react-native-doctor.log
npm run ios -- --no-packager 2>&1 | tee ~/로그/debug-build.log

캐시 삭제는 마지막 조치로 남겨야 합니다. 반복해서 캐시를 지우면 근본 원인이 사라지는 것이 아니라 다음 실행까지 숨겨질 뿐입니다.

디버그 빌드와 릴리스 보관 파일은 따로 검증합니다

첫 번째 목표는 앱 스토어 업로드가 아닙니다. 먼저 디버그 경로를 통과시켜 자바스크립트 번들, 네이티브 모듈, 코드 생성, 자원 파일과 시뮬레이터 대상이 함께 작동하는지 확인해야 합니다.

6. 시뮬레이터에서 디버그 경로를 확인합니다

원격 그래픽 화면은 엑스코드 설정과 시뮬레이터 조작에 적합합니다. 반대로 SSH는 같은 명령을 반복 실행하고 로그를 저장하는 데 적합합니다. 두 연결 방식을 같은 사용 경험으로 보면 안 됩니다.

npx react-native start --reset-cache

별도 터미널에서 프로젝트를 실행합니다.

npx react-native run-ios --simulator "<시뮬레이터 이름>"

여기서 확인할 항목은 다음과 같습니다.

• 메트로 서버가 연결됩니다.
• 앱이 시뮬레이터에서 실행됩니다.
• 사용자 정의 네이티브 모듈이 로드됩니다.
• 권한 요청과 자원 파일이 정상입니다.
• 코드 생성 단계가 종료됩니다.
• 디버그 로그에 로컬 절대 경로가 나타나지 않습니다.

실패 원인은 네 단계로 분리합니다.

1. 의존성 복원 실패
2. 소스 컴파일 실패
3. 라이브러리 링크 실패
4. 앱 실행 또는 런타임 실패

이 구분이 없으면 팟 설치 성공을 전체 빌드 성공으로 오해하게 됩니다.

7. 릴리스 설정에서 보관 파일을 생성합니다

애플은 배포 방식과 관계없이 먼저 보관 파일을 생성하고, 이후 검증과 업로드 절차를 진행하도록 안내합니다. 엑스코드의 보관 파일은 디버깅 정보가 포함된 빌드 묶음이며, 배포 설정에 따라 다시 포장됩니다. (developer.apple.com)

그래픽 화면에서는 다음 순서로 진행합니다.

1. 워크스페이스 파일을 엽니다.
2. 실제 기기용 실행 대상을 선택합니다.
3. 스킴을 릴리스 설정으로 변경합니다.
4. 제품 메뉴에서 보관을 실행합니다.
5. 정리 도구에서 보관 파일을 확인합니다.
6. 검증을 실행합니다.

명령줄에서도 프로젝트에 맞게 확인할 수 있습니다.

xcodebuild \
  -workspace ios/<프로젝트>.xcworkspace \
  -scheme <스킴> \
  -configuration Release \
  -destination "generic/platform=iOS" \
  archive \
  -archivePath ~/보관/<프로젝트>.xcarchive

자리표시자는 실제 값으로 바꾸되, 문서나 저장소에 비밀 정보를 남기지 않아야 합니다.

보관 실패 시 다음 항목을 우선 확인합니다.

• 번들 식별자와 앱 스토어 커넥트 앱 기록이 일치합니다.
• 팀 식별자와 서명 대상이 올바릅니다.
• 권한 파일이 릴리스 설정에 포함됩니다.
• 릴리스 스킴이 올바른 워크스페이스를 가리킵니다.
• 빌드 단계에서 노드 경로를 찾습니다.
• 사용자 정의 팟이 릴리스 설정에서도 링크됩니다.
• 버전 번호와 빌드 번호가 기존 업로드와 충돌하지 않습니다.

서명, 업로드와 심사 제출은 서로 다른 상태입니다

보관 파일 생성에 성공했다고 바로 앱이 올라간 것은 아닙니다. 다음 상태를 따로 기록해야 합니다.

• 보관 파일 생성 완료
• 보관 파일 검증 완료
• 내보내기 또는 업로드 시작
• 앱 스토어 커넥트 처리 중
• 처리 완료
• 빌드 선택 완료
• 심사 제출 완료

애플 문서에 따르면 업로드된 빌드는 시스템 처리가 끝난 뒤 앱 스토어 커넥트에 표시됩니다. 번들 식별자와 버전 번호는 앱 기록과 연결되고, 빌드 번호는 업로드된 빌드를 구분하는 데 사용됩니다. (developer.apple.com)

8. 서명 정보는 제한된 방식으로 주입합니다

서명 인증서, API 키, 비밀번호와 개인 키 경로를 다음 위치에 저장하지 않아야 합니다.

• 공개 저장소
• 프로젝트의 환경 파일
• 팀 채팅
• 명령 기록
• 공유 문서의 평문

대신 제한된 권한의 계정과 비밀 저장소를 사용합니다. 예를 들면 명령은 다음처럼 자리표시자로 작성할 수 있습니다.

export 팀식별자="<팀 식별자>"
export 앱식별자="<앱 식별자>"
export 키경로="$HOME/비밀/<키 파일>"

작업이 끝난 뒤에는 셸 세션과 임시 파일을 정리합니다.

unset 팀식별자 앱식별자 키경로
history -d <명령 번호> 2>/dev/null || true

애플은 업로드 방법으로 엑스코드, 전송 도구, 명령줄 도구와 앱 스토어 커넥트 응용 프로그래밍 인터페이스를 지원합니다. API를 사용할 때는 JSON 웹 토큰 인증을 사용하므로 키의 권한과 보관 위치를 별도로 관리해야 합니다. (developer.apple.com)

9. 앱 스토어 커넥트에서 처리 상태를 확인합니다

업로드 뒤에는 바로 심사 제출 화면으로 이동하지 않습니다. 먼저 빌드 처리 상태를 확인합니다. 애플은 처리 중, 실패, 완료 상태를 구분하며, 처리 중 상태가 오래 지속되면 오류 조사 절차가 필요하다고 안내합니다. (developer.apple.com)

빌드가 보이지 않을 때는 다음을 확인합니다.

• 업로드한 번들 식별자가 앱 기록과 같습니다.
• 버전 번호가 올바른 앱 버전과 연결됩니다.
• 빌드 번호가 이전 업로드와 중복되지 않습니다.
• 내보내기 규정 질문이 남아 있지 않습니다.
• 처리 완료 메일이나 오류 기록이 도착했습니다.

빌드가 처리 완료된 뒤에도 앱 버전에 연결하고 저장해야 합니다. 애플 문서에서도 업로드된 빌드를 선택한 뒤 버전 기록에 연결하는 별도 단계를 안내합니다. (developer.apple.com)

조건에 따라 임시 환경과 상시 환경을 나눕니다

리액트 네이티브 0.86 아이오에스 클라우드 빌드 환경을 선택할 때 중요한 것은 단순한 접속 가능 여부가 아닙니다. 의존성 복원, 그래픽 조작, SSH 실행, 서명 작업, 로그 보관과 재접속 후 상태가 함께 유지되어야 합니다.

다음 조건으로 선택하면 됩니다.

• 릴리스 직전에만 빌드한다면 빠른 전달과 초기 환경 복원이 쉬운 임시 원격 맥을 선택합니다.
• 매주 여러 차례 빌드한다면 작업 폴더와 도구 체인이 유지되는 상시 환경을 선택합니다.
• 시뮬레이터와 엑스코드를 자주 조작한다면 그래픽 원격 접속을 우선합니다.
• 반복 명령과 자동화가 중심이라면 SSH 접근과 로그 저장을 우선합니다.
• 인증서와 키체인을 직접 관리해야 한다면 전체 관리자 권한과 분리된 계정 정책을 확인합니다.
• 물리 아이폰을 직접 연결해야 한다면 원격 맥이 해당 장치 연결 방식을 지원하는지 먼저 확인합니다.

원격 맥의 지역과 접속 방식을 비교할 때는 맥 미니 렌탈 지역별 안내에서 실제 제공 조건을 먼저 확인하는 편이 좋습니다. 장기간 사용할 예정이라면 맥 미니 렌탈 요금 비교도 함께 검토해야 합니다.

첫 주에는 성공보다 복구 가능성을 검증합니다

첫 보관 파일이 생성된 뒤 최소한 다음 흐름을 다시 실행해야 합니다.

1. 원격 맥에서 작업 폴더를 새로 복원합니다.
2. 잠금 파일을 사용해 자바스크립트 의존성을 설치합니다.
3. 아이오에스 팟 의존성을 다시 생성합니다.
4. 디버그 시뮬레이터 빌드를 실행합니다.
5. SSH 연결에서 같은 빌드 명령을 실행합니다.
6. 릴리스 보관 파일을 다시 생성합니다.
7. 서명 정보가 필요한 업로드를 검증합니다.
8. 원격 접속을 끊었다가 다시 연결합니다.
9. 로그와 보관 파일의 위치를 확인합니다.
10. 실패 시 이전 빌드로 되돌리는 절차를 기록합니다.

이 과정을 통과해야 원격 맥이 단순한 일회성 컴퓨터가 아니라 복구 가능한 아이오에스 빌드 서버가 됩니다. 특히 환경 복원, 로그 보관, 인증 정보 종료와 작업 폴더 지속성은 첫 성공보다 장기 운영에 더 큰 영향을 줍니다.

현재 윈도우나 리눅스 환경만으로 계속 진행하면 아이오에스 네이티브 의존성, 엑스코드 설정, 서명과 시뮬레이터 검증을 분리해서 처리하기 어렵습니다. 공개된 빌드 서비스는 세부 설정과 로그 접근이 제한될 수 있고, 개인 맥을 새로 구매하면 발행 빈도가 낮은 개발자에게 하드웨어와 유지 관리 비용이 남습니다. 이 경우 SFTPMAC의 원격 맥은 실제 맥 환경, 관리자 권한, 그래픽 접속과 SSH를 함께 제공하는 대안이 될 수 있습니다. 단, 장기간 매일 무거운 빌드를 실행하거나 물리 아이폰 연결이 필수라면 직접 보유한 맥이 더 적합할 수 있습니다. 첫 보관 파일 이후의 사용 빈도와 복구 요구를 기준으로 선택하는 것이 안전합니다.