使用Capacitor和Capgo Build在Windows上构建iOS应用

传统上，构建iOS应用意味着一个东西：您需要Xcode，而Xcode意味着macOS。这种约束如果您的整个团队都在Windows或Linux上，或者您只是不想维护一个Mac构建机器，是很烦人的。

__CAPGO_KEEP_0__和__CAPGO_KEEP_1__的组合 Capacitor (生成原生 iOS 项目) 和 Capgo Build (在云端编译和签名它) 让您从 Windows 工作站上进行 iOS 构建和 TestFlight 提交。

本指南展示了一种实用的工作流程，适合团队使用：

像普通 Web 项目一样在 Windows 上开发。
在您的仓库中 ios/ (以便原生状态可重现)。
在本地 cap sync (以便您的 Web 构建被复制到 iOS 项目中)。
使用 Capgo Build 触发 iOS 云构建。

您实际构建的内容

There are two separate “builds” in a Capacitor app:

Web build (您的JS/HTML/CSS):您在Windows上进行本地操作。
Native build (Xcode archive, signing, upload): Capgo Build在Mac硬件上在云端进行此操作。

这是关键： Capgo Build会编译本机项目，但它期望您的Web资产已经同步到 ios/.

前提条件

一个正常工作的 Capacitor 应用程序（任何框架都可以）。
一个Apple开发者账户。
App Store Connect对您要上传的应用程序的访问权限（用于TestFlight/App Store提交）。
您的 Capgo 账户和 API token（CAPGO_TOKEN).

1）创建或准备您的 Capacitor 应用程序（Windows）

如果您已经有一个Web应用程序，请跳过 Capacitor 步骤。

Vite 示例：

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

构建必须生成静态资产（对于 Vite 来说，这是 dist/ 2) 添加 __CAPGO_KEEP_0__ 和 iOS 平台

bun run build

安装 Capacitor:

Install Capacitor:

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

此时您将拥有一个

bunx cap init
bunx cap add ios

目录。将其提交到 Git。 __CAPGO_KEEP_0__ Build 将编译内部 ios/ directory. Commit it to git. Capgo Build compiles what is inside ios/3) 在 iOS 构建之前始终同步 Web 资产

每次更改您的 Web 应用时，在 Windows 上执行此序列：

这是将构建的 Web 资产复制到本机 iOS 项目（__CAPGO_KEEP_0__ Build 将实际编译的文件）

bun run build
bunx cap sync ios

cap sync is what copies your built web assets into the native iOS project (the files Capgo Build will actually compile).

4) 安装并验证 Capgo CLI

Capgo 构建由 Capgo CLI 触发。使用 bun bunx:

bunx @capgo/cli@latest login

或通过 shell/CI 中的环境变量设置您的令牌：

export CAPGO_TOKEN="your_api_key_here"

5) 配置 iOS 签名以进行 Cloud 构建

要构建 iOS，您需要签名材料：

Apple 发行证书（.p12)及其密码
分发配置文件（.mobileprovision)
App Store Connect API 密钥（AuthKey_XXXXXX.p8)和元数据（Key ID、Issuer ID、Team ID）

如果您仍然需要生成这些文件，请遵循 Capgo 文档：

管理凭证 (如何保存和如何)
如何获取iOS证书和配置文件

最简单的路径是：使用任何可用的Mac、同事或一次性租用创建/导出这些文件，然后从Windows重复使用它们进行每次构建。

一旦您在本地有这些文件，请将它们保存为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"

提示：在CI中，将凭证文件以base64编码的形式存储为机密，运行时解码，然后运行相同的命令。 build credentials save 6) 从Windows触发iOS构建

从您的应用程序文件夹：

您将在终端中看到实时日志。如果您的App Store Connect密钥已配置，__CAPGO_KEEP_0__ Build可以自动将生成的构建提交到TestFlight。

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__ Build适用于本机更改：

添加/删除Capgo插件

adding/removing Capacitor plugins
更改原生权限
更改图标/启动画面
更新 Capacitor
任何 Swift/Objective-C 的更改

对于日常 UI 调整和 JavaScript 修复，您通常希望 实时更新 (OTA)，因此您不需要每次重建原生二进制文件。

一个好的团队工作流程是：

使用实时更新频繁的 Web 更改。
在需要原生更改时偶尔使用 Capgo 构建。

常见的 Windows pitfall (和解决方案)

忘记 cap sync: 如果您的 UI 变更在 iOS 构建中丢失，很可能是您构建了 Web 应用，但没有将其同步到 ios/.
未提交 ios/: Capgo Build 编译本机项目。如果文件夹不在 Git 中（或不在您的构建上下文中），则无法重现您的应用。
插件更改而不重建本机: 添加插件是一种本机更改；计划后续的 Capgo Build 运行（以及商店提交）。

概要

您无法在 Windows 上运行 Xcode，但您可以从 Windows 上

将您的 Web 应用包装在 Capacitor (ios/ 在您的仓库中)
在本地构建 Web 资产，然后 cap sync.
Use Capgo Build to compile, sign, and submit your iOS binary from the CLI.