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

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__ Capacitor __CAPGO_KEEP_1__ Capgo 빌드 (클라우드에서 컴파일하고 서명할 수 있도록) Windows 워크스테이션에서 iOS 빌드 및 TestFlight 제출을 할 수 있게 해줍니다.

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

Windows에서 일반적인 웹 프로젝트처럼 개발하세요.
__CAPGO_KEEP_0__를 ios/ 리포지토리에 유지하세요 (그래서 원본 상태가 재현 가능합니다).
__CAPGO_KEEP_0__를 cap sync 로컬에서 실행하세요 (그래서 웹 빌드는 iOS 프로젝트에 복사됩니다).
Capgo 빌드를 클라우드에서 트리거하세요.

실제로 빌드하는 곳

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

웹 빌드 (your JS/HTML/CSS): Windows 환경에서 이 작업을 직접합니다.
Native build (Xcode archive, signing, upload): Capgo Build은 Mac 하드웨어에서 클라우드에서 이 작업을 수행합니다.

이 분리는 가장 중요합니다: Capgo Build은 네이티브 프로젝트를 컴파일하지만 웹 자산이 이미 동기화된 상태로 기대합니다. ios/.

필수 조건

작동하는 Capacitor 앱 (어떤 프레임워크든 상관 없습니다.)
Apple Developer 계정
업로드하고자 하는 앱에 대한 App Store Connect 접근 권한.
Capgo 계정과 API 토큰 (CAPGO_TOKEN).

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

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

Vite 예시:

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

Build가 정적 자산을 생성해야 합니다 (Vite의 경우, 이건 dist/ 기본적으로):

bun run build

2) iOS 플랫폼에 Capacitor과 iOS 플랫폼을 추가하세요.

Capacitor을 설치하세요:

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

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

bunx cap init
bunx cap add ios

이 시점에서 __CAPGO_KEEP_0__ Build는 ios/ directory. Commit it to git. Capgo Build compiles what is inside ios/3) iOS 빌드 전에 항상 웹 자산을 Sync하세요.

Windows에서 웹 앱을 변경할 때마다 이 시퀀스를 수행하세요:

이것은 빌드한 웹 자산을 네이티브 iOS 프로젝트에 복사합니다 (__CAPGO_KEEP_0__ Build가 실제로 컴파일할 파일).

bun run build
bunx cap sync ios

cap sync 4) Capgo과 __CAPGO_KEEP_1__을 설치하고 인증하세요.

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

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

bunx @capgo/cli@latest login

__CAPGO_KEEP_1__

export CAPGO_TOKEN="your_api_key_here"

__CAPGO_KEEP_2__

__CAPGO_KEEP_3__

또는 셸/CI에서 환경 변수를 통해 토큰을 설정하세요:.p125) iOS 클라우드 빌드에 대한 iOS Signing을 구성하세요
iOS 빌드를 위해 서명 자료가 필요합니다:.mobileprovision)
App Store Connect API key (AuthKey_XXXXXX.p8) 및 비밀번호

If you still need to generate these files, follow the Capgo documentation:

앱 스토어 커넥트 __CAPGO_KEEP_0__ 키 ( ) 및 메타데이터 (키 ID, 발급자 ID, 팀 ID)입니다. 만약 여전히 이러한 파일을 생성해야 한다면 __CAPGO_KEEP_0__ 문서를 따라하세요:
How to Get iOS Certificates and Provisioning Profiles

iOS 인증서와 배포 프로파일을 얻는 가장 쉬운 방법은: 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"

Tip: CI에서 credential 파일을 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

You will see real-time logs in your terminal. If your App Store Connect key is configured, Capgo Build can submit the resulting build to TestFlight automatically.

__CAPGO_KEEP_0__ 빌드는 네이티브 변경 사항에만 적용됩니다:

Capgo 플러그인을 추가/제거하거나 네이티브 권한을 변경합니다.

Capacitor Build:
__CAPGO_KEEP_0__ Build can
아이콘/스플래시 변경
Capacitor 업데이트
Swift/Objective-C 변경 사항

일상적인 UI 조정 및 자바스크립트 수정을 위해 일반적으로 원하는 실시간 업데이트 (OTA), 따라서 매번 네이티브 바이너리를 재빌드하지 않습니다.

좋은 팀 워크플로우는:

실시간 업데이트 사용하여 자주 변경되는 웹 변경 사항
Capgo 빌드를 간혹 사용하여 네이티브 변경 사항이 필요할 때

공통 Windows 오류 (및 해결 방법)

잊어버리기 cap sync: 네이티브 빌드에서 UI 변경 사항이 누락된 경우, iOS 빌드에서 웹 앱을 빌드했지만 Sync를 수행하지 않았을 가능성이 있습니다. ios/.
Not committing ios/: Capgo Build은 네이티브 프로젝트를 컴파일합니다. 폴더가 Git에 있지 않거나(또는 빌드 컨텍스트에 없다면) 빌드는 앱을 재현할 수 없습니다.
: 플러그인을 추가하는 것은 네이티브 변경입니다; __CAPGO_KEEP_0__ Build를 실행하고(그리고 스토어 제출) 나중에 계획하세요.: adding a plugin is a native change; plan a Capgo Build run (and a store submission) afterward.

Xcode를 Windows에서 실행할 수 없지만, Windows에서 iOS 앱을 배포할 수 있습니다:

__CAPGO_KEEP_0__ ( 리포지토리 내에 있습니다.) 웹 앱을 __CAPGO_KEEP_0__ Build로 컴파일, 서명, 제출하여 iOS 바이너리를 __CAPGO_KEEP_1__에서 컴파일하세요.

Wrap your web app with Capacitor (ios/ Wrap your web app with __CAPGO_KEEP_0__ (in your repo).
Build web assets locally, then Use __CAPGO_KEEP_0__ Build to compile, sign, and submit your iOS binary from the __CAPGO_KEEP_1__. cap sync.
Use Capgo Build to compile, sign, and submit your iOS binary from the CLI.

Build an iOS App from Windows with Capacitor and Capgo Build