Flutter·React Native·Unity iOS 빌드 가이드

다른 검색어로 찾아보세요

오류 메시지에서 signing, Xcode, VNC 같은 키워드 하나만 입력해 보세요. 그래도 찾을 수 없다면 오류 원문을 보존해 문의를 접수하세요.

문의 접수

환경부터 점검

이 세 단계에서는 접속과 도구만 확인합니다. 아직 운영 인증서를 가져오거나 모든 의존성을 한꺼번에 업그레이드하지 마세요.

접속 정보 확인

콘솔에 로그인해 해당 주문과 인스턴스 상세 정보를 여세요. 노드, 실행 상태, 페이지에 표시된 접속 주소, 포트, 인증 정보를 확인합니다.

접속 주소는 주문 번호가 아닙니다. 인스턴스가 아직 준비 중이면 먼저 상태를 확인하세요. 오류가 있으면 설정을 반복해서 초기화하지 말고 주문 번호와 함께 문의를 접수하세요.

주문 확인
macOS에 로그인

로컬 VNC 클라이언트에 주소, 포트, 비밀번호를 각각 입력하세요. 처음 연결할 때는 해상도를 낮게 설정하고 키보드, 마우스, 창 조작이 정상인지 확인합니다.

명령줄이 필요하면 인스턴스에서 제공한 SSH 접속 정보를 사용하세요. 처음 연결할 때 호스트 지문을 확인하고, 지문이 예상과 다르게 바뀌었다면 인증 정보를 입력하지 말고 원인을 확인하세요.

화면이 끊긴다고 빌드가 중단된 것은 아닙니다. 먼저 로컬 네트워크를 확인한 다음 해상도를 낮추세요. 빌드만 실행한다면 SSH를 사용해도 됩니다.
03
개발 도구 확인

Xcode 정식 버전이 설치되어 있는지 확인하고 한 번 실행해 구성 요소를 초기화하세요. 명령줄 도구는 독립 도구 디렉터리가 아니라 이번 빌드에 사용할 Xcode를 가리켜야 합니다.
```
xcode-select -p
xcodebuild -version
xcodebuild -showsdks
```
iOS SDK가 없다면 먼저 Xcode 구성 요소를 설치하세요. 라이선스 안내가 표시될 때만 라이선스를 처리하고, 디렉터리를 바꾸는 것으로 실제 SDK 누락을 감추지 마세요.

Flutter 사용하기

먼저 doctor 실행

프로젝트, 의존성 잠금 파일, 필요한 리소스를 함께 Mac으로 옮기세요. 프로젝트에서 사용 중인 Flutter 버전을 유지하고, 비즈니스 코드를 변경하기 전에 환경 문제부터 해결합니다.

필수 도구 설치

Flutter SDK, Xcode 정식 버전, CocoaPods를 준비하세요. 프로젝트에서 Flutter 버전이나 Ruby 도구 체인을 지정했다면 저장소의 기준에 맞춰 먼저 설치해 로컬과 빌드 머신의 버전이 달라지지 않게 합니다.

진단을 실행한 뒤 iOS 도구 체인 관련 안내를 하나씩 해결하세요. 기기 연결 안내는 아카이브를 막지 않을 수 있지만, Xcode, SDK, 서명 설정이 없다면 먼저 해결해야 합니다.

두 가지 검증 구분하기

컴파일 성공 여부만 확인하려면 서명 없이 Release 빌드를 먼저 실행할 수 있습니다. 이 빌드는 서명된 설치 패키지를 대신하지 않으며 배포용 산출물로 바로 사용할 수도 없습니다.

.ipa를 내보내려면 Xcode의 Signing & Capabilities에서 Team, Bundle Identifier, 인증서, 프로비저닝 프로파일을 확인한 다음 정식 빌드를 실행하세요.

순서대로 실행

flutter --version
flutter doctor -v
flutter pub get
flutter build ios --release --no-codesign
flutter build ipa --release

마지막 명령을 실행하려면 서명 설정이 완전히 구성되어 있어야 합니다. 출력 위치와 내보내기 방법은 현재 Flutter 버전과 명령 출력에 따라 다르므로, 완료 후 산출물을 로컬로 내려받아 확인하세요.

실패한 단계부터 확인하고 캐시 정리는 나중에 결정하세요
오류 단서	먼저 할 일	먼저 하지 말 것
CocoaPods가 설치되지 않음	CocoaPods가 설치되어 있는지, 현재 터미널에서 pod 명령을 찾을 수 있는지 확인하세요.	iOS 프로젝트 전체를 먼저 삭제하지 마세요.
프로비저닝 프로파일 / 서명 없음	Bundle Identifier, Team, 내보내기 유형이 서로 맞는지 확인하고 프로비저닝 프로파일의 유효 기간을 살펴보세요.	의존성 오류와 서명 오류를 한꺼번에 해결하려 하지 마세요.
배포 대상 버전	플러그인 요구 사항을 확인하고 프로젝트와 Podfile의 최소 iOS 버전을 일치시킨 다음 의존성을 설치하세요.	하나의 target만 수정한 뒤 바로 아카이브를 다시 시도하지 마세요.

React Native 사용하기

의존성 버전 고정

저장소에서 Node, Ruby, 패키지 관리자 관련 기준을 먼저 확인하세요. 잠금 파일을 유지해 빌드 머신에서 팀의 기존 환경을 재현하고, 의존성 버전을 새로 선택하지 않도록 합니다.

먼저 JS 의존성 설치

프로젝트의 잠금 파일에 지정된 npm, Yarn 또는 기존 패키지 관리자를 사용하세요. 아래 명령은 package-lock.json이 있는 npm 프로젝트에 해당합니다. 다른 프로젝트는 기존 설치 명령을 사용하세요.

저장소에 Gemfile이 있다면 Bundler로 CocoaPods 버전을 고정하세요. Gemfile이 없는 경우에만 프로젝트에서 요구하는 버전의 pod 명령을 직접 사용하고, 전역 도구 체인과 프로젝트 도구 체인을 섞지 마세요.

그다음 workspace 열기

Pods를 설치한 뒤 iOS 디렉터리의 .xcworkspace를 여세요. .xcodeproj만 열면 안 됩니다. 실제 앱에 해당하는 scheme을 선택하고 Release 구성으로 아카이브하세요.

아카이브 전에 버전 번호, 빌드 번호, 서명을 확인하세요. 아카이브가 완료되면 Organizer에서 테스트 또는 배포 목적에 맞게 내보냅니다. 시뮬레이터용 빌드는 기기에 설치할 패키지를 대신할 수 없습니다.

프로젝트 환경 재현

node --version
ruby --version
npm ci
bundle install
cd ios
bundle exec pod install

Bundler 명령 두 개는 프로젝트에 Gemfile이 있다는 전제입니다. 설치 로그에 오류가 나면 먼저 첫 번째 오류와 관련 버전을 보존한 뒤 해결을 시도하세요.

Hermes만 따로 확인

Hermes 컴파일에 실패하면 React Native 버전, Pods 잠금 파일, Xcode 버전, 네이티브 의존성의 호환성을 먼저 확인하세요. 로그에 Node 스크립트를 찾을 수 없다는 내용이 있으면 빌드 스크립트에서 사용하는 Node 경로를 확인합니다. 먼저 Hermes를 끄거나 잠금 파일을 모두 삭제하지 마세요. 프로젝트 동작과 의존성 결과가 달라질 수 있습니다.

Unity 사용하기

프로젝트를 옮겨 내보내기

Windows에서 게임을 계속 편집하고 클라우드 Mac에서 Xcode 빌드와 서명을 완료하세요. 프로젝트 파일 하나만이 아니라 내보낸 디렉터리 전체를 옮겨야 합니다.

모듈 먼저 확인

현재 Unity 버전과 설치 방식이 로컬에서 iOS 프로젝트를 내보낼 수 있는지 확인하고, 해당 iOS Build Support를 설치하세요. 로컬에서 내보낼 수 없다면 Unity 프로젝트를 Mac으로 옮긴 뒤 동일한 에디터 버전으로 빌드합니다.

내보내기 전에 Bundle Identifier, 스크립팅 백엔드, 최소 OS 버전, 플러그인 플랫폼 설정을 확인하고 이번에 사용한 구성을 저장하세요.

디렉터리 전체 전송

내보낸 Xcode 프로젝트와 리소스, 네이티브 플러그인, 빌드 스크립트를 함께 압축해 전송하세요. 압축을 푼 뒤 디렉터리 구조를 확인해 숨김 설정 파일이 누락되거나 .xcodeproj만 전송되지 않았는지 확인합니다.

플러그인에 CocoaPods가 필요하다면 안내된 의존성 설치 단계를 먼저 실행한 다음 생성된 workspace를 여세요. 임시 압축 디렉터리에서 바로 빌드하지 마세요.

오류를 단계별로 확인

IL2CPP 또는 링크 오류가 나면 첫 번째 컴파일 오류부터 확인하고 네이티브 라이브러리 아키텍처, framework 참조, 플러그인 버전을 점검하세요. 빌드가 통과한 뒤 인증서와 프로비저닝 프로파일이 맞지 않는 문제를 해결합니다.

대용량 리소스 번들은 Pro 요금제를 고려할 수 있습니다. 사양은 M4 Pro / 64GB / 2TB SSD입니다. 프로젝트 이름이 아니라 리소스 크기와 사용 가능한 저장 공간을 기준으로 확인하세요.

Unity 프로젝트를 다시 내보내면 Xcode에서 직접 수정한 내용이 덮어써질 수 있습니다. 필요한 설정을 기록하고, 스크립트로 처리할 수 있는 변경은 프로젝트 빌드 과정에 반영해 다음 빌드에서 반복 작업하지 않도록 하세요.

용어 알아보기

접속, 하드웨어, 서명은 서로 다른 단계입니다. 용어를 정확히 이해하면 문의할 때 불필요한 확인 과정을 줄일 수 있습니다.

물리 노드: 실제로 macOS를 실행하는 Mac 하드웨어입니다. 선택한 노드 위치는 원격 조작과 파일 전송 경로에 영향을 주지만 프로젝트의 서명 요건은 바꾸지 않습니다.
단독 할당: 대여 기간 동안 사용자에게 단독 할당되는 물리 Mac입니다. 가상 머신이 아니며 CPU와 메모리를 다른 사용자와 공유하지 않습니다. 프로젝트 권한과 빌드 인증 정보는 직접 관리해야 합니다.
VNC: 원격 그래픽 데스크톱을 보고 조작하는 접속 방식입니다. Xcode를 처음 구성하거나 아카이브를 확인할 때 적합하며, 화면 반응은 로컬 네트워크와 해상도에 따라 달라집니다.
self-hosted runner: 직접 관리하는 머신에 설치하는 CI 실행기입니다. 빌드는 해당 Mac에서 실행되며 등록 토큰, 작업 권한, 정리 정책은 팀에서 구성해야 합니다.
통합 메모리: Apple Silicon에서 프로세서와 그래픽 작업이 함께 사용하는 메모리입니다. 프로젝트 규모, 병렬 컴파일, 동시에 실행하는 도구가 모두 이 메모리를 사용합니다.
서명 인증서: 앱 서명에 사용하는 신원 정보로, 서명할 때는 보통 해당 인증서에 연결된 개인 키도 필요합니다. 인증서만 가져오고 연결된 개인 키가 없으면 서명을 완료하지 못할 수 있습니다.
Provisioning Profile: 앱 식별자, 서명 권한, 배포 목적을 연결하는 프로비저닝 프로파일입니다. 인증서, Team, 앱 기능, 내보내기 유형과 모두 일치해야 합니다.
.ipa: iOS 기기용 앱 패키지입니다. 파일이 생성되어도 모든 기기에 설치할 수 있는 것은 아닙니다. 실제 설치 및 배포 범위는 서명과 내보내기 방식에 따라 달라집니다.

빌드 후 확인할 사항

빌드 산출물뿐 아니라 대여 기간과 데이터 관리도 챙기세요. 원격 데스크톱 창을 닫아도 대여는 종료되지 않습니다.

아직 작업이 끝나지 않았어요. 어떻게 연장하나요?

만료 전에 콘솔에 접속해 현재 서비스의 갱신 메뉴, 청구 내역, 만료일을 확인하세요. 주기와 금액을 확인한 뒤 결제를 완료하고 서비스 기간이 갱신되었는지 다시 확인합니다. 결제는 제출했지만 상태가 업데이트되지 않았다면 주문 번호와 거래 증빙을 첨부해 문의하세요. 결제 화면 캡처만으로 갱신 완료를 판단하지 마세요.

빌드가 끝났어요. 어떻게 종료하나요?

서비스는 일·주·월·분기 단위로 선결제되며, 만료 시 갱신하지 않으면 중지됩니다. 작업을 일찍 마쳤다면 먼저 파일을 내보낸 다음 콘솔에서 서비스 기간과 이용 가능한 조치를 확인하세요. VNC에서 로그아웃하거나 SSH를 종료하거나 시스템을 직접 끄는 것만으로는 주문의 결제 상태를 확인할 수 없으며 자동 환불을 의미하지도 않습니다.

만료 후에도 파일이 남아 있나요?

서비스 약관에 따라 만료로 서비스가 중지된 뒤 데이터가 삭제되므로, 중지된 머신을 백업 저장소로 사용하지 마세요. 만료 전에 소스 코드, .ipa, Archive, dSYM, 필요한 설정을 내보내고 로컬에서 파일을 열 수 있는지 확인하세요. 인증서와 개인 키는 팀 정책에 따라 안전하게 백업하고, 더 이상 사용하지 않는 민감한 인증 정보는 원격 머신에서 삭제하세요. 만료 후 다시 접속하거나 파일을 복구할 수 있다고 가정하지 마세요.

갱신 시 어떤 결제 수단을 사용할 수 있나요?

USDT-TRC20 및 Visa / Mastercard / Amex(Stripe)만 지원하며 모든 결제는 미국 달러(USD)로 처리됩니다. 실제 사용 가능한 결제 게이트웨이는 백엔드 응답을 확인하세요. 결제 문의에는 주문 번호, 결제 수단, 거래 상태를 포함하세요. 이메일이나 문의에 전체 카드 번호, 보안 코드, 비밀번호, 개인 키를 보내지 마세요.

오류 정보를 구체적으로 전달하세요

주문 후 문의는 콘솔에서 접수하세요. 구매 전 요금제 상담이나 로그인할 수 없는 경우에는 문의 페이지에서 이메일 연락처를 확인할 수 있습니다. 문의는 접수 순서대로 처리되며, 확인되지 않은 답변 시간을 약속하지 않습니다.

재현 조건 포함

주문 번호, 프레임워크 버전, Xcode 버전, 작업 단계, 오류 발생 시각과 시간대를 적어 주세요. 빌드 문제라면 마지막 줄의 ‘실패’ 메시지만 캡처하지 말고 첫 번째 오류와 앞뒤 로그를 함께 제공하세요.

연락처 확인

민감한 정보 삭제

로그에서 비밀번호, 토큰, 개인 키, 고객 정보를 먼저 가리세요. 가동률 관련 요청에는 영향을 받은 시간대를 추가하고, 결제 문의에는 거래 식별 정보를 제공하세요. 관련 없는 프로젝트 소스 코드는 첨부하지 마세요.

연결이 끊겼다면 VNC와 SSH가 모두 영향을 받았는지, 로컬 네트워크를 전환한 뒤에도 문제가 있었는지 알려 주세요. 접속 문제와 빌드 문제를 구분하는 데 도움이 됩니다.

처음부터 iOS 빌드하기