Expo 프로젝트 iOS Test Flight 배포 가이드 (feat. xCode)

Expo (React native) 프로젝트를 iOS Test Flight에 배포하는 방법을 단계별로 안내합니다. xCode를 사용하여 빌드하고, Test Flight 업로드까지의 과정을 다룹니다.

Expo 프로젝트 iOS TestFlight 배포 (EAS 없이: prebuild + Xcode)

이 글은 EAS를 사용하지 않고, Expo 프로젝트를 prebuild로 iOS 네이티브 프로젝트를 생성한 뒤 Xcode에서 Archive → TestFlight 업로드까지 진행하는 배포 절차를 정리합니다.

기본 전제 조건

• macOS + Xcode 설치
• Apple Developer Program 가입(유료)
• App Store Connect 앱 생성(앱 이름/번들 ID 준비)

1. 배포 전 확인 체크리스트

배포에 필요한 핵심 값은 다음 3가지입니다.

• Bundle Identifier: 예) com.mycompany.myapp
• Version (CFBundleShortVersionString): 예) 1.0.0
• Build Number (CFBundleVersion): 예) 21 (업로드할 때마다 반드시 증가)

특히 Build Number는 TestFlight 업로드 시 매번 증가해야 합니다.

2. app.json(app.config) iOS 설정

Expo 프로젝트 설정에서 iOS 배포에 필요한 값을 먼저 고정합니다.

예시(app.json 또는 app.config.js):

{
  "expo": {
    "name": "MyApp",
    "slug": "myapp",
    "version": "1.0.0",
    "ios": {
      "bundleIdentifier": "com.mycompany.myapp",
      "buildNumber": "21"
    }
  }
}

• expo.version → App 버전(표시용)
• ios.buildNumber → iOS 빌드 넘버(업로드마다 +1)
• ios.bundleIdentifier → App Store Connect에서 만든 앱의 번들 ID와 동일해야 함

이미 iOS 프로젝트가 있는 상태에서 buildNumber만 올릴 때는 Xcode에서 올려도 되지만, 운영에서는 한 곳(app.json 또는 Xcode)으로 기준을 통일하는 게 안전합니다.

3. iOS 네이티브 프로젝트 생성 (prebuild)

# iOS 네이티브 프로젝트 생성
npx expo prebuild -p ios

이미 ios/ 폴더가 있고, 네이티브 설정을 다시 반영해야 한다면:

npx expo prebuild -p ios --clean

• --clean은 ios/를 재생성하므로 Xcode에서 직접 수정한 내용이 있었다면 사라질 수 있습니다.

4. CocoaPods 설치

cd ios # /ios 디렉토리로 이동
pod install
 
# macOS 기준 폴더 열기
open .
 
cd ..

이후 Xcode는 반드시 .xcworkspace를 열어야 합니다.

ios 폴더

5. Xcode에서 프로젝트 열기

• ios/MyApp.xcworkspace 열기

  xcode가 설치되어 있으면 .xcworkspace 파일을 더블클릭하면 자동으로 xcode가 열립니다.

6. Signing 설정 (서명/프로비저닝)

Xcode → Targets(앱 타겟) → Signing & Capabilities

상단 탭 메뉴 에서 Signing & Capabilities

1. Team 선택
2. Bundle Identifier 확인
3. Automatically manage signing 체크(권장)

번들 ID가 App Store Connect의 앱과 다르면 업로드가 실패합니다.

각 역할은 다음과 같습니다.

Xcode Signing 설정

7) Release 빌드로 Archive 만들기

1. Xcode 상단 디바이스 선택에서

   • 실제 기기 또는
   • Any iOS Device (arm64)

2. 메뉴: Product → Archive

Xcode Archive 메뉴

Xcode 빌드 대기

아카이브가 성공하면 Organizer 창이 열립니다.

8) TestFlight 업로드 (Distribute App)

Organizer에서 해당 아카이브 선택 후:

Xcode Archive Organizer

1. Distribute App
2. App Store Connect 선택
3. Upload 선택
4. 안내대로 진행
5. 업로드 완료 후 App Store Connect에서 처리 대기

업로드가 끝나면 App Store Connect → TestFlight 탭에서 빌드가 보입니다.

9) App Store Connect에서 TestFlight 배포

1. App Store Connect → 내 앱 → TestFlight
2. 업로드된 빌드 선택
3. (필요 시) Export Compliance/암호화 질문 응답
4. 내부 테스트(Internal Testing) 또는 외부 테스트(External Testing) 그룹에 추가

• Internal Testing: 팀원(최대 100명) 중심, 심사 부담이 비교적 적음
• External Testing: 외부 테스터 초대, 최초 1회는 보통 베타 앱 심사 과정이 들어감

10) 다음 업로드를 위한 버전 규칙

TestFlight는 동일 버전이라도 Build Number가 증가해야 새 빌드를 업로드할 수 있습니다.

• 예) 이전 업로드가 1.0.0 (21) 이라면
• 다음 업로드는 1.0.0 (22) 또는 1.0.1 (22)

운영 팁:

• 기능 수정/재업로드: buildNumber만 올리고 업로드
• 스토어에 표시될 버전 변경 필요: version도 함께 올리고 업로드

트러블슈팅(배포에서 자주 만나는 것들)

A. “The bundle version must be higher than the previously uploaded version”

• buildNumber가 이전 업로드보다 낮거나 동일한 상태입니다.
• ios.buildNumber(또는 Xcode의 Build) 값을 올린 뒤 다시 Archive/Upload 하세요.

B. “The provided entity includes an attribute with a value that has already been used”

• 보통 버전/빌드 조합이 중복되었거나, App Store Connect 메타데이터/번들 ID 충돌 등에서 발생합니다.
• 가장 먼저 Version + Build Number가 새 값인지 확인하세요.

정리

• expo prebuild -p ios로 ios/ 생성
• pod install 후 .xcworkspace 열기
• Signing 설정
• Product → Archive
• Distribute App → App Store Connect → Upload
• App Store Connect TestFlight에서 테스터 배포

이 순서만 정확히 지키면, EAS 없이도 TestFlight 배포가 가능합니다.