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

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

组合 Capacitor (生成原生iOS项目)和 Capgo 构建 (以编译并在云中签名)使您可以从 Windows 工作站进行 iOS 构建和 TestFlight 提交。

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

在 Windows 上开发像普通 Web 项目一样。
保留 ios/ 在您的仓库中（以便原生状态可重现）。
在本地运行（以便将 Web 构建复制到 iOS 项目中）。 cap sync 使用 __CAPGO_KEEP_0__ 构建触发 iOS 云构建。
Trigger an iOS cloud build with Capgo Build.

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

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

iOS 构建 (您的 JS/HTML/CSS): 在 Windows 上您可以这样做。
原生构建 (Xcode archive, signing, upload): Capgo Build 在云端使用 Mac 硬件来做这个。

关键点在于：Capgo Build 会编译原生项目，但它期待您的 web 资产已经同步到 ios/.

前提条件

一个正常工作的 Capacitor 应用（任何框架都可以）
一个 Apple 开发者账户
您要上传的应用的 App Store Connect 访问权限（用于 TestFlight/App Store 提交）
您的 Capgo 账户和 API token (CAPGO_TOKEN).

1) 在 Windows 上创建或准备您的 Capacitor 应用

如果您已经有一个 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/每次您更改您的Web应用程序时，在Windows上执行以下序列：

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

4）安装并验证__CAPGO_KEEP_0__ __CAPGO_KEEP_1__

bun run build
bunx cap sync ios

cap sync is what copies your built web assets into the native iOS project (the files Capgo Build will actually compile).

4) Install and Authenticate the 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 文档：

管理凭据（如何保存和保存） (什么需要保存和如何保存)
How to Get iOS Certificates and Provisioning Profiles

最简单的方法是：创建/导出这些一次（通常使用任何可用的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插件（Capawesome Diff Plugins Capgo）
修改图标/启动画面
更新 Capacitor
任何 Swift/Objective-C 的修改

对于日常的 UI 调整和 JavaScript 修复，您通常希望 实时更新 context: 首页问题/解决方案部分。角色：部分或页面标题。见于：页面 premium-support.astro。消息键 `ps_help_updates_title` (Ps Help Updates Title)。

(OTA)，因此您不需要每次重建原生二进制文件。

一个好的团队工作流程是：
Use Capgo Build occasionally when native changes are needed.

使用 __CAPGO_KEEP_0__ Build 偶尔进行原生修改。

常见的 Windows pitfall (和解决方案) cap sync忘记了：如果您的 UI 变更在 iOS 构建中丢失，您很可能已经构建了 web 应用，但没有同步它到 ios/.
Not committing ios/: Capgo Build会编译本机项目。如果文件夹不在git (或不在您的构建上下文) 中，无法重现您的应用。
: 添加插件是本机更改；之后计划__CAPGO_KEEP_0__ Build运行（和商店提交）。: adding a plugin is a native change; plan a Capgo Build run (and a store submission) afterward.

您无法在Windows上运行Xcode，但您

可以 从Windows将iOS应用程序运送出去： 将您的web应用程序包装在__CAPGO_KEEP_0__ (

Wrap your web app with Capacitor (ios/ 在本地构建web资产，然后
使用__CAPGO_KEEP_0__ Build将您的iOS二进制文件编译、签名并从__CAPGO_KEEP_1__ 提交。 cap sync.
Use Capgo Build to compile, sign, and submit your iOS binary from the CLI.

继续使用 Build an iOS App from Windows with Capacitor 和 Capgo Build

如果您正在使用 Build an iOS App from Windows with Capacitor 和 Capgo Build 来规划 CI/CD 自动化，连接它与 Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 原生构建为产品工作流程在 Capgo 原生构建中 Capgo 集成为产品工作流程在 Capgo 集成中 CI/CD 集成为 CI/CD 集成的实现细节 GitHub Actions Integration 为 GitHub Actions Integration 的实现细节。

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