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

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

组合 Capacitor (生成原生 iOS 项目) Capgo Build (在云中编译和签名)

让您从 Windows 工作站进行 iOS 构建和 TestFlight 提交。

本指南展示了一种实用工作流程，适用于团队：
在 Windows 上开发，如正常的 Web 项目。 ios/ 保留
在您的仓库中（以便原生状态可复制）。 cap sync 在本地运行（以便您的 Web 构建被复制到 iOS 项目中）。
触发一个 iOS 云构建：Capgo 构建。

您实际构建的位置

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

Web 构建 （您的 JS/HTML/CSS）：您可以在 Windows 本地进行此操作。
原生构建 （Xcode archive，签名，上传）：Capgo 构建在云端的 Mac 硬件上进行此操作。

这种分离是关键：Capgo 构建会编译原生项目，但它期望您的 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

2) 添加 __CAPGO_KEEP_0__ 和 iOS 平台 dist/ 安装 __CAPGO_KEEP_0__：

bun run build

2) Add Capacitor and the iOS Platform

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

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

1) Create or Prepare Your __CAPGO_KEEP_0__ App (Windows)

bunx cap init
bunx cap add ios

If you already have a web app, skip to the __CAPGO_KEEP_0__ steps. ios/ directory. Commit it to git. Capgo Build compiles what is inside ios/Build must produce static assets (for Vite this is

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 Connect API密钥（AuthKey_XXXXXX.p8）和元数据（Key ID、Issuer ID、Team ID）

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

管理凭据 (保存什么和如何)
如何获取iOS证书和分发配置文件

最简单的路径是：创建/导出这些一次（通常使用任何可用的Mac、同事或一次性租用），然后从Windows重复使用它们以便每次后续构建

一旦您在本地有了这些文件，请将它们保存到Capgo构建中：

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__构建可以自动将生成的构建提交到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) 快速迭代：仅限 Web 的实时更新

Capgo Build 是用于原生变化：

添加/删除 Capacitor 插件
上下文：Capawesome 比较页面的 HTML 文本片段（父级键 `capwesome_diff_plugins_capgo`）。页面/区域：Capawesome 比较页面。角色：长期营销或法律段落。见于：页面 capwesome.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `capwesome_diff_plugins_capgo` (Capwesome Diff Plugins Capgo)。
更改原生权限
updating Capacitor
更新 __CAPGO_KEEP_0__

任何 Swift/Objective-C 变化 对于日常 UI 调整和 JavaScript 修复，您通常希望 实时更新

上下文：首页问题/解决方案部分。角色：部分或页面标题。见于：页面 premium-support.astro。消息键 `ps_help_updates_title` (Ps Help Updates Title)。

(OTA)，因此您不需要每次重建原生二进制文件。
使用Capgo Build时，偶尔需要进行native的修改。

常见的Windows陷阱（和解决方案）

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

总结

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

将您的 Web 应用程序包裹在 Capacitor (ios/ 在您的仓库中).
在本地构建 Web 资产，然后 cap sync.
Use Capgo Build to compile, sign, and submit your iOS binary from the 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应用程序