Windows에서 iOS 앱을 빌드하기 위해 Capacitor와 Capgo 빌드를 사용하세요.

iOS 앱을 빌드하는 전통적인 방법은 한 가지 일 수 있습니다: Xcode가 필요하고 Xcode는 macOS를 의미합니다. 이 제약은 Windows 또는 Linux에서 일하는 팀이거나 Mac 빌드 머신을 유지 관리하고 싶지 않다면 불편할 수 있습니다.

Capacitor와 Capacitor (iOS 네이티브 프로젝트를 생성하기 위해)와 Capgo Build (클라우드에서 컴파일 및 서명하기 위해)가 iOS 빌드 및 TestFlight 제출을 Windows 워크스테이션에서 수행할 수 있도록 해줍니다.

이 안내서에서는 팀에서 잘 작동하는 실용적인 워크플로우를 보여줍니다.

Windows에서 일반 웹 프로젝트처럼 개발하세요.
__CAPGO_KEEP_0__ ios/ 로 유지하세요 (네이티브 상태가 재현 가능하도록).
__CAPGO_KEEP_0__ cap sync 로컬에서 실행하세요 (웹 빌드가 iOS 프로젝트에 복사됩니다).
iOS 클라우드 빌드 트리거하기: Capgo 빌드.

실제로 무엇을 빌드하는 곳

Capacitor 앱에는 두 가지 별개의 '빌드'가 있습니다:

웹 빌드 (JS/HTML/CSS): 이 작업은 Windows에서 로컬로 수행합니다.
네이티브 빌드 (Xcode 아카이브, 서명, 업로드): Capgo 빌드는 Mac 하드웨어에서 클라우드에서 이 작업을 수행합니다.

이 분리는 핵심입니다: Capgo 빌드는 네이티브 프로젝트를 컴파일하지만 웹 자산이 이미 동기화된 상태로 기대합니다. ios/.

사전 요구 사항

Capacitor 앱이 작동 중이어야 합니다 (어떤 프레임워크도 괜찮습니다).
Apple 개발자 계정
업로드하고 싶은 앱에 대한 App Store Connect 접근 권한 (TestFlight/App Store 제출을 위해)
당신의 Capgo 계정과 API 토큰 (CAPGO_TOKEN).

1) Capacitor 앱을 만들거나 준비하세요 (Windows)

웹 앱이 이미 있는 경우 Capacitor 단계로 건너 뛰세요.

Vite와의 예시:

bun create vite@latest my-app
cd my-app
bun install

__CAPGO_KEEP_0__ 빌드는 정적 자산을 생성해야 합니다 (Vite의 경우 기본값입니다): dist/ 2) __CAPGO_KEEP_0__ 및 iOS 플랫폼을 추가하세요

bun run build

Capacitor 설치:

Capacitor 초기화 및 iOS 플랫폼 폴더를 생성하세요:

bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli

이 시점에서 __CAPGO_KEEP_0__ 디렉토리가 생성됩니다. Git에 커밋하세요. __CAPGO_KEEP_0__ 빌드는 내부에 있는 것을 컴파일하기 때문에 버전이 관리되고 reproducible해야 합니다.

bunx cap init
bunx cap add ios

__CAPGO_KEEP_0__ ios/ Capgo ios/__CAPGO_KEEP_0__

3) iOS에서 빌드하기 전에 항상 웹 자산을 동기화하세요.

윈도우에서 웹 앱을 변경할 때마다 이 순서를 반복하세요.

bun run build
bunx cap sync ios

cap sync 이것은 웹 앱을 빌드한 후 네이티브 iOS 프로젝트에 웹 자산을 복사하는 것입니다 (Capgo 빌드는 실제로 컴파일됩니다).

4) Capgo과 CLI을 설치하고 인증하세요.

Capgo 빌드는 Capgo CLI를 통해 트리거됩니다. bun을 사용하여 bunx:

bunx @capgo/cli@latest login

또는 쉘/CI에서 환경 변수를 통해 토큰을 설정하세요.

export CAPGO_TOKEN="your_api_key_here"

5) Cloud 빌드에 대한 iOS 서명 구성

iOS 빌드하려면 서명 자료가 필요합니다:

Apple Distribution 인증서 (.p12) 및 비밀번호
배포 프로파일 (.mobileprovision)
App Store Connect API 키 (AuthKey_XXXXXX.p8인증서 및 메타데이터 (Key ID, Issuer ID, Team ID)

Capgo 문서를 참조하여 여전히 이러한 파일을 생성해야 하는 경우:

인증서 관리 (저장해야 하는 것과 방법)
iOS 인증서 및 배포 프로파일을 얻는 방법

가장 쉬운 방법은: Mac, 팀원, 또는 일회용 임대 중인 Mac을 사용하여 한 번에 생성/수출한 다음 Windows에서 재사용하는 것입니다.

파일을 로컬에 저장한 후 Capgo 빌드에 저장하세요:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "password" \
  --provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey.p8 \
  --apple-key-id "KEY123" \
  --apple-issuer-id "issuer-uuid" \
  --apple-team-id "team-id"

팁: CI에서 자격 증명 파일을 base64로 인코딩하여 비밀로 저장하고 런타임에 디코딩한 다음 동일한 명령어를 실행하세요. build credentials save 6) Windows에서 iOS 빌드를 트리거하세요.

앱 폴더에서:

터미널에서 실시간 로그를 볼 수 있습니다. App Store Connect 키가 구성된 경우 __CAPGO_KEEP_0__ 빌드는 자동으로 테스트 플라이트에 결과 빌드를 제출할 수 있습니다.

bun run build
bunx cap sync ios
bunx @capgo/cli@latest build com.example.app --platform ios --build-mode release

Capgo

7) 빠른 반영: 웹 전용 변경 사항에 대한 실시간 업데이트

Capgo Build는 네이티브 변경 사항에 대한 것입니다:

Capacitor 플러그인을 추가/제거하는 경우
네이티브 권한을 변경하는 경우
아이콘/스플래시를 변경하는 경우
Capacitor를 업데이트 하는 경우
Swift/Objective-C 변경 사항의 경우

일상적인 UI 조정 및 JavaScript 수정에 대해, 일반적으로 Live Updates(실시간 업데이트)를 사용하여 웹 변경 사항을 자주 반영하고 싶습니다. (OTA), 네이티브 바이너리를 매번 다시 빌드하지 않도록 하세요.

좋은 팀 워크플로우는:

자주 반영되는 웹 변경 사항에 대해 Live Updates를 사용하세요.
Capgo Build를 가끔씩 사용하여 Native 변경이 필요할 때.

Windows에서 일반적인 문제점 (및 해결 방법)

UI 변경이 iOS 빌드에서 누락된 경우, iOS 빌드에서 UI 변경이 누락된 경우, 웹 앱을 빌드했지만 iOS 빌드에 동기화하지 않았을 가능성이 있습니다. cap sync소스 코드를 커밋하지 않은 경우 ios/.
__CAPGO_KEEP_0__ Build는 Native 프로젝트를 컴파일합니다. Git에 폴더가 없거나 빌드 컨텍스트에 없으면 빌드는 앱을 재현할 수 없습니다. ios/: Capgo Build compiles the native project. If the folder is not in git (or not in your build context), the build cannot reproduce your app.
Plugin을 추가하는 것은 Native 변경입니다. __CAPGO_KEEP_0__ Build를 실행하고 (그리고 스토어 제출) 나중에 계획하세요.: adding a plugin is a native change; plan a Capgo Build run (and a store submission) afterward.

Windows에서 Xcode를 실행할 수 없습니다. 그러나

Windows에서 iOS 앱을 배포할 수 있습니다: __CAPGO_KEEP_0__ __CAPGO_KEEP_0__

Capacitor (ios/ 을 포함하는) 저장소에 __CAPGO_KEEP_0__를 wrapping합니다.
웹 자산을 로컬에서 빌드하고 cap sync.
Capgo Build를 사용하여 CLI에서 iOS 바이너리를 컴파일, 서명, 제출하세요.

Capacitor와 Capgo Build를 사용하여 Windows에서 iOS 앱을 빌드하세요.

__CAPGO_KEEP_0__를 사용 중이면 Windows에서 iOS 앱을 빌드하는 Capacitor와 Capgo Build를 사용하세요. CI/CD 자동화 계획을 위해 Capgo CI/CD와 연결하세요. Capgo CI/CD에서 제품 워크플로우를 관리하세요. Capgo Native Builds에서 제품 워크플로우를 관리하세요. Capgo Native Builds에서 제품 워크플로우를 관리하세요. Capgo 통합 Capgo 통합을 위한 제품 워크플로우에서 CI/CD 통합 CI/CD 통합의 구현 세부 정보를 위한 GitHub 액션 통합 GitHub 액션 통합의 구현 세부 정보를 위한

윈도우에서 iOS 앱을 빌드하세요: Capacitor을 사용하여 웹 앱을.wrap하고 Capgo 빌드를 사용하여 윈도우 개발 머신에서 테스트 플라이트에 제출할 수 있는 실제 iOS 바이너리를 빌드하세요.