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

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

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

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

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

您实际上构建的位置

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

Web 构建 （您的 JS/HTML/CSS）：您在 Windows 本地进行此操作。
原生构建 （Xcode.archive，签名，上传）： 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) Always Sync Web Assets into iOS Before Building

每次你修改你的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配置文件（.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 快速：仅限 Web 的实时更新

Capgo 本地构建是针对本地变化：

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

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

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

使用实时更新频繁的 Web 变化。
使用 Capgo Build 时，偶尔需要在原生变化时进行构建。

Windows 通常会遇到的常见问题（和解决方案）

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

概要

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

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

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

如果你正在使用 使用 Capacitor 和 Capgo Build 构建一个从Windows的iOS应用 来规划CI/CD自动化，连接它到 Capgo CI/CD 在 Capgo CI/CD 中的产品工作流程中 Capgo Native Builds 在 Capgo Native Builds 中的产品工作流程中, Capgo 集成为产品工作流程在 Capgo 集成中 CI/CD 集成为 CI/CD 集成的实现细节 GitHub 动作集成为 GitHub 动作集成的实现细节

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