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

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

__CAPGO_KEEP_0__ 和 __CAPGO_KEEP_0__ Build 的组合 Capacitor (用于在云中编译和签名它) 让您可以从 Windows 工作站上进行 iOS 构建和 TestFlight 提交。 Capgo Build Martin Donadieu

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

在 Windows 上开发，像普通的 Web 项目一样。
在您的仓库中（以便原生状态可重现）。 ios/ 在本地运行（以便将 Web 构建复制到 iOS 项目中）。
触发一个 iOS 云构建，使用 __CAPGO_KEEP_0__ 构建。 cap sync 实际上你构建了什么
在一个 Capgo 应用中，有两个独立的“构建”：

Web 构建

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

原生构建 (您的 iOS 代码): 在 Windows 上本地进行此操作。
原生构建（iOS） (Xcode archive, signing, upload): Capgo 在 Mac 硬件上云端执行此操作。

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

前置条件

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

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

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

使用Vite的示例：

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

构建必须产生静态资产（对于Vite，这是 dist/ 默认情况下）：

bun run build

2) 在此处添加 Capacitor 和 iOS 平台

安装 Capacitor:

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

初始化并创建 iOS 平台文件夹：

bunx cap init
bunx cap add ios

此时您将拥有一个 ios/ 目录。将其提交到 Git。 Capgo Build 将编译内部内容 ios/,因此您希望它版本化并可重现。

3) 在 iOS 构建之前始终同步 Web 资产

每次您更改 Web 应用时，请在 Windows 上执行以下操作序列：

bun run build
bunx cap sync ios

cap sync 这是将构建的 Web 资产复制到本机 iOS 项目中的工具（Capgo Build 将实际编译的文件）。

4) 安装并验证 Capgo CLI

Capgo Build 通过 Capgo CLI 触发。使用 bun bunx:

bunx @capgo/cli@latest login

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

export CAPGO_TOKEN="your_api_key_here"

5) 为 Cloud 构建配置 iOS 签名

要构建 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 Build

从您的应用程序文件夹：

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

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

7) 快速迭代：仅限 Web 的实时更新

Capgo Build 是用于本机更改：

添加/删除 Capacitor 插件
更改本机权限
更改图标/启动屏幕
更新 Capacitor
任何 Swift/Objective-C 的变化

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

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

使用实时更新频繁的 web 变化。
使用 Capgo Build 偶尔构建原生项目时，需要原生项目的变化。

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

忘记 cap sync: 如果您的 UI 变化在 iOS 构建中丢失，很可能是您构建了 web 应用，但没有同步它到 ios/.
未提交 ios/: Capgo Build 会编译原生项目。如果文件夹不在 git (或不在您的构建上下文中)，则无法重现您的应用。
插件更改不需要原生重建: 添加插件是原生更改; 之后计划一个 Capgo Build 运行（和一个商店提交）。

概要

您无法在 Windows 上运行 Xcode，但您可以从 Windows 上 ship iOS 应用： 将您的 Web 应用包装在 __CAPGO_KEEP_0__ (

Wrap your web app with Capacitor (ios/ 在本地构建 Web 资产，然后
使用 __CAPGO_KEEP_0__ Build 来编译、签名并提交您的 iOS 二进制文件从 __CAPGO_KEEP_1__。 cap sync.
继续使用 Build 从 Windows 上构建 iOS 应用程序的 Capgo 和 CLI Build

Keep going from Build an iOS App from Windows with Capacitor and Capgo Build

__CAPGO_KEEP_0__ 是 Capacitor 的一部分，允许您在 Windows 上构建 iOS 应用程序。 使用Capacitor和Capgo在Windows上构建iOS应用 计划CI/CD自动化，连接它 Capgo CI/CD 在Capgo CI/CD中产品工作流程 Capgo 原生构建在Capgo 原生构建中产品工作流程 Capgo 集成在Capgo 集成中产品工作流程 CI/CD集成在CI/CD集成的实现细节中 GitHub 动作集成在GitHub 动作集成的实现细节中

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