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

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

Capacitor和 Capacitor （生成本机iOS项目）和 Capgo Build （在云中编译和签名它）让您可以从Windows工作站进行iOS构建和TestFlight提交。

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

在Windows上开发像普通Web项目一样。
在您的仓库中保留 ios/ （以便本机状态可重现）。
在本地运行 cap sync （以便您的Web构建被复制到iOS项目中）。
触发一个 iOS 云构建：Capgo Build。

您实际构建的位置

在一个 Capacitor 应用中，有两个独立的“构建”：

Web 构建 (您的 JS/HTML/CSS): 您可以在 Windows 本地进行此操作。
原生构建 (Xcode archive, signing, upload): Capgo Build 在 Mac 硬件上在云中执行此操作。

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

前提条件

一个工作的 Capacitor 应用（任何框架都可以）。
一个 Apple 开发者账户。
您要上传（用于 TestFlight/App Store 提交）的应用的 App Store Connect 访问权限。
Your 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/__CAPGO_KEEP_0__

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) 配置iOS签名以进行Cloud构建

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

Apple Distribution证书（.p12)和其密码
分配配置文件（.mobileprovision)
App Store ConnectAPI密钥（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.

7) Iterate Fast: Live Updates for Web-Only Changes

Capgo Build is for native changes:

添加/删除 Capacitor 插件
改变原生权限
改变图标/启动画面
更新 Capacitor
任何 Swift/Objective-C 变更

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

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

频繁的 Web 变更时，使用实时更新。
使用 Capgo Build 时，偶尔需要进行原生代码的修改。

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

忘记了 cap sync: 如果您的 iOS 构建中缺少 UI 变更，很可能您构建的是 web 应用，但没有将其同步到 ios/.
未提交 ios/: Capgo Build 会编译原生项目。如果该文件夹不在 Git 中（或不在您的构建上下文中），则无法重现您的应用。
插件变更而未进行原生重建: 添加插件是一种原生变更；之后请计划进行 Capgo Build 运行（并提交应用到商店）。

概要

您无法在 Windows 上运行 Xcode，但您可以从 Windows 上将 iOS 应用发布到 App Store：

用 Capacitor (ios/ 在你的仓库中) 包裹你的web应用。
在本地构建web资源， cap sync.
然后使用 Capgo Build 来编译、签名并提交你的iOS二进制文件到 CLI。

继续使用 Capacitor 和 Capgo Build 构建一个从Windows的iOS应用。

如果你正在使用 从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 动作集成实现细节