在 Windows 上用 Capacitor 和 Capgo Build 构建 iOS App

传统上，构建 iOS 应用意味着一件事：你需要 Xcode，而 Xcode 意味着 macOS。如果你的整个团队都在使用 Windows 或 Linux，或者你只是不想维护一台 Mac 构建机器，这个限制就很烦人。

组合使用 Capacitor （用于生成原生 iOS 项目）和 Capgo 构建 （用于在云端编译和签名）让你可以从 Windows 工作站进行 iOS 构建和 TestFlight 提交。

本指南展示了一个在团队中效果良好的实用工作流：

像普通 Web 项目一样在 Windows 上进行开发。
保留 ios/ 在你的仓库中（以便原生状态可复现）。
运行 cap sync 本地（这样 Web 构建会被复制到 iOS 项目中）。
用 Capgo Build 触发 iOS 云构建。

实际构建内容与位置

在 Capacitor 应用里，有两种不同的“构建”：

Web 构建 （你的 JS/HTML/CSS）：这部分你在 Windows 本地完成。
Native Build （Xcode 归档、签名、上传）：Capgo Build 会在云端的 Mac 硬件上完成这些操作。

这种分离是关键：Capgo Build 会编译原生项目，但它要求你的 Web 资源已同步到 ios/.

前提条件

一个可运行的 Capacitor 应用（任何 framework 都可以）。
一个 Apple Developer 账号。
你要上传的应用的 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/ 默认行为）：

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) 构建前始终将 Web 资源同步到 iOS

每次修改 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 中通过环境变量设置 token：

export CAPGO_TOKEN="your_api_key_here"

5) 配置云构建的 iOS 签名

构建 iOS 需要签名材料：

Apple Distribution 证书（.p12）及其密码
Provisioning profile（.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 编码后存为 secrets，运行时解码，然后运行相同的 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 更改使用 Live Update

Capgo Build 适用于原生更改：

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

对于日常的 UI 调整和 JavaScript 修复，您通常希望使用 Capgo Live Updates （OTA），这样无需每次重新构建原生二进制文件。

良好的团队工作流程是：

Web 端变更频繁时，请使用 Live Updates。
需要原生变更时，偶尔使用 Capgo Build。

Windows 常见坑（及解决方案）

忘记同步 cap sync：如果 iOS 构建中缺少 UI 变更，可能是你构建了 Web 应用但未将其同步到 ios/.
未提交代码 ios/：Capgo Build 会编译原生项目。如果该文件夹不在 git（或构建上下文）中，构建将无法复现你的应用。
插件变更未重新构建原生代码：添加插件属于原生变更；之后需规划一次 Capgo Build 运行（以及商店提交）。

总结

你无法在 Windows 上运行 Xcode，但你可以做到在 Windows 上发布 iOS 应用：

使用 Capacitor 封装你的 Web 应用（ios/ 在你的仓库中）。
在本地构建 Web 资源，然后 cap sync.
使用 Capgo Build 从 CLI 编译、签名并提交你的 iOS 二进制文件。

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

如果你正在使用 在 Windows 上用 Capacitor 和 Capgo Build 构建 iOS App 规划 CI/CD 自动化，并将其与 Capgo CI/CD 集成用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成用于 Capgo 集成中的产品工作流， CI/CD 集成了解 CI/CD 集成的实现细节，以及 GitHub Actions 集成有关 GitHub Actions 集成的实现细节。