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

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

组合 Capacitor (生成本机 iOS 项目) Capgo Build (在云中编译并签名)让您从Windows工作站上完成iOS构建和TestFlight提交。

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

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

您实际上构建了什么

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

Web构建 (您的 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令牌（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

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

bunx cap init
bunx cap add ios

3）始终将Web资产同步到iOS之前构建 ios/ directory. Commit it to git. Capgo Build compiles what is inside ios/这是将构建的Web资产复制到本机iOS项目（__CAPGO_KEEP_0__ Build将实际编译的文件）的过程。

4）安装并验证__CAPGO_KEEP_0 CAPGO_KEEP_1__

5) Build iOS App

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 中设置你的 token

export CAPGO_TOKEN="your_api_key_here"

5) 配置 iOS 签名（Cloud Builds）

为了构建 iOS，你需要签名材料：

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

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

管理凭据（保存什么和如何） __CAPGO_KEEP_0__
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
HTML文本片段来自更长的Capgo UI字符串（父键`capwesome_diff_plugins_capgo`）。页面/区域：Capawesome比较页面。角色：长期营销或法律段落。见：页面capwesome.astro。保留Capgo产品/品牌和开发人员术语完全不变。消息键`capwesome_diff_plugins_capgo`（Capwesome 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 Native Builds 在 Capgo Native Builds 中的产品流程 Capgo Integrations 在 Capgo Integrations 中的产品流程 CI/CD Integration CI/CD Integration 的实现细节 GitHub Actions Integration 为 GitHub Actions Integration 的实现细节。