Construire une application iOS à partir de Windows avec Capacitor et Capgo Build

Construire une application iOS traditionnellement signifie une chose : vous avez besoin de Xcode, et Xcode signifie macOS. Cette contrainte est gênante si votre équipe entière est sur Windows ou Linux, ou si vous n'avez simplement pas envie de maintenir une machine de build Mac.

Le combo de Capacitor (pour générer le projet natif iOS) et Capgo Construction (pour compiler et signer cela dans le cloud) vous permet de réaliser des builds iOS et des soumissions de TestFlight à partir d'un poste de travail Windows.

Cette guide présente un workflow pragmatique qui fonctionne bien en équipe :

Développez sur Windows comme un projet web normal.
Conservation ios/ dans votre dépôt (afin que l'état natif soit réproducible).
Exécution cap sync localement (afin que votre build web soit copié dans le projet iOS).
Déclenchez un build iOS cloud avec Capgo Construction.

Ce que vous construisez réellement où

Il existe deux « builds » séparés dans une application Capacitor :

Build web (votre JS/HTML/CSS) : vous faites cela localement sur Windows.
Compilation native (archive Xcode, signature, téléchargement) : Capgo Build fait cela sur matériel Mac dans le cloud.

C'est cette séparation qui est la clé : Capgo Build compile le projet natif, mais il s'attend à ce que vos actifs web soient déjà synchronisés dans ios/.

Prérequis

Un compte Capacitor fonctionnel (n'importe quel framework est acceptable).
Un compte développeur Apple.
D'accès à App Store Connect pour l'application que vous souhaitez télécharger (pour TestFlight/App Store).
Votre compte Capgo et votre jeton API (CAPGO_TOKEN).

1) Créez ou Préparez votre application Capacitor (Windows)

Si vous avez déjà une application web, sautez directement aux étapes Capacitor.

Exemple avec Vite :

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

La construction doit produire des actifs statiques (pour Vite, c'est par défaut) : dist/ 2) Ajoutez __CAPGO_KEEP_0__ et la plateforme iOS

bun run build

Installez Capacitor :

Install Capacitor:

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

À ce stade, vous disposerez d'un

bunx cap init
bunx cap add ios

dossier. Commitez-le dans git. __CAPGO_KEEP_0__ Build compile ce qui se trouve à l'intérieur ios/ directory. Commit it to git. Capgo Build compiles what is inside ios/3) Synchronisez toujours les actifs Web dans iOS avant de construire

Chaque fois que vous modifiez votre application Web, effectuez cette séquence sur Windows :

ceci est ce qui copie vos actifs Web construits dans le projet natif iOS (les fichiers __CAPGO_KEEP_0__ Build seront en réalité compilés).

bun run build
bunx cap sync ios

cap sync 4) Installez et authentifiez le Capgo __CAPGO_KEEP_1__

4) Installez et authentifiez le Capgo CLI

Capgo Build is triggered via the Capgo CLI. With bun, use bunx:

bunx @capgo/cli@latest login

Avec __CAPGO_KEEP_3__, utilisez

export CAPGO_TOKEN="your_api_key_here"

Ou définissez votre jeton via une variable d'environnement dans votre shell/CI :

5) Configurez la signature iOS pour les builds Cloud

Pour construire iOS, vous avez besoin de matériel de signature :.p12Certificat de distribution d'Apple (
) et son mot de passe.mobileprovision)
App Store Connect API key (AuthKey_XXXXXX.p8Clé d'App Store Connect __CAPGO_KEEP_0__ (

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

Si vous avez encore besoin de générer ces fichiers, suivez la documentation __CAPGO_KEEP_0__ : Gestion des identifiants (ce qu'il faut sauvegarder et comment faire)
Comment obtenir les certificats et les profils de provisionnement iOS

La voie la plus facile est : créer/exporter ces éléments une fois (souvent en utilisant n'importe quel Mac disponible, un collègue ou un location à usage unique), puis les réutiliser à partir de Windows pour chaque build ultérieur.

Une fois que vous avez les fichiers localement, enregistrez-les pour la Capgo Build :

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"

Conseil : en CI, stockez les fichiers de clés base64-encodés en tant que secrets, décodez-les en temps de exécution, puis exécutez le même build credentials save commande.

6) Déclenchez une build iOS à partir de Windows

À partir de votre dossier d'application :

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

Vous verrez des journaux en temps réel dans votre terminal. Si votre clé App Store Connect est configurée, la Capgo Build peut soumettre la build résultante à TestFlight automatiquement.

7) Itérez rapidement : Mises à jour en temps réel pour les modifications Web uniquement

La Capgo Build est réservée aux modifications natives :

ajout/removal de plugins Capacitor
modification des permissions natives
changer les icônes/d'entrée
mettre à jour Capacitor
toutes les modifications Swift/Objective-C

Pour les ajustements quotidiens de l'interface utilisateur et les corrections JavaScript, vous voulez généralement Mises à jour en temps réel (OTA), afin de ne pas reconstruire le binôme natif à chaque fois.

Un bon flux de travail d'équipe est :

Utilisez Mises à jour en temps réel pour les modifications web fréquentes.
Utilisez Capgo Build occasionnellement lorsque des changements natifs sont nécessaires.

Problèmes courants de Windows (et corrections)

Oublier cap sync: si vos modifications d'interface utilisateur manquent dans la version iOS, vous avez probablement construit l'application web mais n'avez pas synchronisé son contenu ios/.
Pas de commit ios/: Capgo La compilation du projet natif. Si le dossier n'est pas dans Git (ou pas dans votre contexte de build), la build ne peut pas reproduire votre application.
Changements de plugin sans recompilation native: l'ajout d'un plugin est un changement natif; prévoyez une Capgo Build (et une soumission de magasin) par la suite.

Résumé

Vous ne pouvez pas exécuter Xcode sur Windows, mais vous pouvez envoyer des applications iOS à partir de Windows : Enveloppez votre application web avec __CAPGO_KEEP_0__ (

Wrap your web app with Capacitor (ios/ Compilez les actifs web localement, puis
Utilisez __CAPGO_KEEP_0__ Build pour compiler, signer et soumettre votre fichier binaire iOS à partir du __CAPGO_KEEP_1__. cap sync.
Vous pouvez utiliser Capgo Build pour compiler, signer et soumettre votre fichier binaire iOS à partir du CLI.