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

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

__CAPGO_KEEP_0__和__CAPGO_KEEP_1__的组合 Capacitor（生成原生iOS项目）和 (to generate the native iOS project) and Capgo Build 让您在 Windows 工作站上从云中编译和签署 iOS 构建和 TestFlight 提交。

本指南展示了一种在团队中工作的实用流程：

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

Web 构建

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

Web 构建 (你的JS/HTML/CSS): 在 Windows 上你做这个。
原生构建 (Xcode archive, signing, upload): Capgo 构建在 Mac 硬件上在云端做这个。

这分离是关键： Capgo 构建编译原生项目，但它期待你的 web 资产已经同步到 ios/.

前提条件

一个工作的 Capacitor 应用程序（任何框架都可以）。
一个 Apple 开发者账户。
你要上传（测试/商店提交）的应用程序的 App Store Connect 访问权限。
你的 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/3) 在构建之前始终同步Web资产到iOS

每次您更改Web应用时，在Windows上执行此序列：

这是将构建的Web资产复制到本机iOS项目（__CAPGO_KEEP_0__ Build将实际编译的文件）

bun run build
bunx cap sync ios

cap sync 4) 安装并验证Capgo __CAPGO_KEEP_1__

4) 安装并验证Capgo CLI

Capgo 在 Capgo CLI 中触发构建。使用 bun， bunx:

bunx @capgo/cli@latest login

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

export CAPGO_TOKEN="your_api_key_here"

5) 配置 iOS 签名以支持云构建

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

Apple Distribution 证书（.p12)及其密码
分发配置文件（.mobileprovision)
App Store Connect API 密钥（AuthKey_XXXXXX.p8)和元数据（Key ID、Issuer ID、Team ID）

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

管理凭据（保存什么和如何） Managing Credentials (什么需要保存，如何保存)
如何获取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.

__CAPGO_KEEP_0__ Build适用于本机更改：

添加/删除Capgo插件

adding/removing Capacitor plugins
添加/删除__CAPGO_KEEP_0__插件
更改图标/启动画面
更新 Capacitor
任何 Swift/Objective-C 的变化

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

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

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

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

忘记：如果您的 UI 变化在 iOS 构建中丢失了，您很可能已经构建了 Web 应用，但没有将其同步到 cap sync忘记：如果您的 UI 变化在 iOS 构建中丢失了，您很可能已经构建了 Web 应用，但没有将其同步到原生项目中 ios/.
不提交 ios/Capgo Build会编译native项目。如果文件夹不在git（或不在你的构建上下文）中，无法重现你的app。
插件变更不需要native重建：添加插件是native变更；之后计划Capgo Build运行（和商店提交）

概要

你无法在Windows上运行Xcode，但你可以从Windows上

Wrap your web app with Capacitor (ios/ 将你的web app.wrap在__CAPGO_KEEP_0__ (
在你的仓库中）。 cap sync.
在本地构建web资产，然后使用Capgo Build编译、签名并提交你的iOS二进制文件从CLI.

从 Windows 上使用 Capacitor 和 Capgo 构建 iOS 应用

如果您正在使用 从 Windows 上使用 Capacitor 和 Capgo 构建 iOS 应用 来规划 CI/CD 自动化，连接它与 Capgo CI/CD 在 Capgo CI/CD 中的产品工作流程中， Capgo 原生构建在 Capgo 原生构建中， Capgo 集成在 Capgo 集成中， CI/CD 集成在 CI/CD 集成中实现的细节中， GitHub Actions Integration 为实现详细信息，请参阅 GitHub Actions Integration。

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