Capacitor 项目可以把前端和原生工程拆开处理。React、Vue、Angular、TypeScript、Node.js、单元测试、Web 调试，以及 npm run build 这类任务，通常可以继续放在 Windows 或 Linux。Capacitor 官方环境文档要求使用 Node.js 22 或更高版本，这部分并不等于必须购买 Mac。

真正需要 macOS 的，是 iOS 工程之后的链路：

• 生成或同步 ios 目录；
• 使用 Xcode 打开原生工程；
• 调用 xcodebuild 编译 iOS 目标；
• 在 Simulator 中启动和回归；
• 创建 Archive；
• 处理证书、私钥、Provisioning Profile 和上传制品。

Capacitor 官方文档明确写明，构建 iOS 应用需要 macOS、Xcode 与 Xcode Command Line Tools；Capacitor 8 的最低 Xcode 要求是 Xcode 26.0。而 Capacitor 8.5 为适配 Xcode 27，引入了 UIScene 项目迁移要求。

因此，Windows 或 Linux 不能单独替代完整的 iOS 工具链，但可以继续承担前端和非原生阶段：

• ✅ 可以在 Windows 或 Linux 完成 Web 代码开发、依赖安装和前端构建。
• ❌ 不能在纯 Windows 或 Linux 环境中直接替代 Xcode 完成完整 iOS 构建、Simulator 验证和签名归档。
• ⚠️ 云端或远程环境可以承接 macOS 阶段，但它仍然必须是真实可用的 macOS 工具链，而不是普通 Linux 云主机。

不要一拿到远程节点就直接升级生产项目。先把它当成一次可撤销的兼容性试运行。

建议准备一个独立工作区，并记录以下内容：

• Capacitor 核心包、@capacitor/ios 与 CLI 的实际版本；
• Node.js、npm 或其他包管理器版本；
• 活动 Xcode 路径和 xcode-select 状态；
• 项目使用 SPM 还是 CocoaPods；
• 当前 Git 分支、提交哈希和锁定文件；
• 项目中的原生插件清单；
• 恢复入口，例如重新克隆、重置工作区或切换 Xcode。

可以先执行：

node --version
xcodebuild -version
xcode-select -p
git rev-parse HEAD
npm ls @capacitor/core @capacitor/ios @capacitor/cli

这些命令的价值不在于“看起来专业”，而在于之后失败时能回答：是 Xcode 变化、依赖解析变化，还是项目本身的问题。

为什么不能只在现有工作区里试？
旧的 DerivedData、本地缓存、未提交的 Info.plist 修改、全局安装的 CLI，都会把错误隐藏起来。你需要先完成一次全新克隆，再生成最小 Web 产物并同步到 iOS 工程。

git clone <REPOSITORY_URL> <PROJECT_PATH>
cd <PROJECT_PATH>

npm ci
npm run build
npx cap sync ios

<REPOSITORY_URL>、<PROJECT_PATH>、Bundle ID、Team ID 和账户都应使用你自己的值或占位符。不要把真实凭据写进脚本、日志或仓库。

Capacitor 8.5 的关键变化不是“换一个 Xcode 版本”这么简单。官方更新指南说明，Xcode 27 要求项目采用 iOS UIScene 生命周期；对符合模板结构的项目，CLI 可以尝试自动迁移。

在 Xcode 27 前，至少要检查这几类项目文件：

1. SceneDelegate.swift 是否存在，并加入 App target。
2. Info.plist 是否包含 UIApplicationSceneManifest。
3. AppDelegate.swift 是否提供 configurationForConnecting。
4. SceneDelegate.swift 是否注册到 Xcode 项目的 Sources Build Phase。
5. 自定义深链、Universal Link、后台恢复逻辑是否仍然挂在旧的 AppDelegate 回调上。

对于模板形状正常的工程，可以尝试：

npm i -D @capacitor/cli@^8.5.0
npx cap migrate
npx cap sync ios

但不要把自动迁移当成验收结果。Capacitor 官方更新指南提醒，手写 SceneDelegate、定制 URL 处理或复杂原生插件项目，仍然需要人工审计。引入 scene manifest 后，旧的 application(_:open:options:) 和 application(_:continue:restorationHandler:) 不再是可靠入口，相关逻辑需要转移到 SceneDelegate。

需要重点修改或复核哪些文件？
通常要检查 SceneDelegate.swift、Info.plist、AppDelegate.swift 和 Xcode 项目文件注册。若项目使用自定义 CAPBridgeViewController、深链、推送或后台生命周期代码，还要逐项确认回调是否仍然到达。

SPM 与 CocoaPods：不要把迁移依赖管理器设成硬门槛

Capacitor 8 新项目默认倾向使用 Swift Package Manager，CocoaPods 仍可作为替代方案。官方环境文档将 CocoaPods 列为可选依赖，并说明需要时才安装 Homebrew 与 CocoaPods；不使用 CocoaPods 的项目可以直接走 SPM。

因此，首次构建的判断顺序应是：

• 新项目：优先确认 SPM 能否解析并构建；
• 存量 CocoaPods 项目：先保持现状完成基线构建；
• 依赖迁移：作为单独变更验证，不要与 UIScene、插件升级和签名配置同时进行；
• 失败时：先锁定依赖管理器，再定位具体包或插件，不要同时执行多个迁移动作。

如果你在 Windows 上只看到前端依赖安装成功，不代表 iOS 原生依赖已经验证完成。真正的证据应该来自远程 macOS 节点上的 xcodebuild 日志、解析结果和构建产物。

首次构建不要马上进入签名发布。先验证工程能否在全新工作区中完成不签名或开发配置构建。

示例命令如下，路径和 Scheme 使用占位符：

xcodebuild \
  -workspace <IOS_WORKSPACE> \
  -scheme <SCHEME_NAME> \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=<SIMULATOR_NAME>' \
  clean build \
  | tee <BUILD_LOG_PATH>

你需要保存至少三类证据：

• 命令完整输出；
• xcresult 或测试结果目录；
• 构建产物与 Git 提交哈希的对应关系。

Capacitor 的 iOS 文档支持通过命令行运行 iOS 项目，也支持在 Xcode 中选择设备或 Simulator 启动。Apple 文档则说明，Simulator 运行在 Mac 上，不能完整模拟真实设备的性能或硬件特性。(developer.apple.com)

失败时什么时候停止？
如果出现 Swift 编译错误、SPM 解析错误、UIScene 回调缺失、资源未找到或插件头文件异常，应停在构建阶段。不要在工程尚未稳定时导入生产证书、私钥或 App Store Connect API 密钥。

空白模板能启动，只能证明基础工程大致可用。对实际项目来说，最容易暴露问题的是插件生命周期、权限和回调路径。

至少选择项目真正使用的一类插件进行验证：

• 深链或 Universal Link；
• 推送通知；
• 相机、相册或定位；
• 文件系统；
• 自定义 Swift 插件；
• 依赖原生权限的支付或登录插件。

建议按下面的证据组合进行测试：

• 冷启动：应用被杀死后，通过 URL 或通知进入；
• 热启动：应用已打开时再次触发 URL 或插件调用；
• 后台恢复：切到后台后重新回到前台；
• 权限拒绝：用户拒绝权限后，JavaScript 层是否得到可处理的错误；
• 重启恢复：远程节点重启后，依赖是否仍能解析，服务是否能够重新连接。

Capacitor 8.5 更新指南特别要求检查 pause、resume、自定义 URL Scheme 和 Universal Link。它还指出，旧的 AppDelegate 生命周期方法在采用 scene 生命周期后可能不再被调用。

远程 CI 中如何验证 Capacitor 原生插件？
把插件测试分成两层。第一层在远程 Mac 的 Simulator 中验证启动、页面、权限提示和自动化回归；第二层把相机、推送、蓝牙、生物识别等真实硬件或发布质量测试留给真机计划。远程节点可以运行 Simulator，但不能把 Simulator 当成真机的完全替代品。Apple 也明确提醒，设备特有功能必须在物理设备上验证。

远程访问方式也要区分：

• SSH：适合执行 npm、xcodebuild、测试和日志收集；
• VNC 或网页控制台：适合查看 Xcode、Simulator、证书提示和图形化故障；
• 真机：需要提前规划设备连接、授权和维护责任。

一个更稳妥的 CI 结构是：

Windows 或 Linux 节点负责：

• TypeScript 类型检查；
• ESLint；
• 单元测试；
• Web 构建；
• 静态资源校验；
• 依赖锁文件检查。

macOS 节点负责：

• npx cap sync ios；
• SPM 或 CocoaPods 解析；
• xcodebuild build；
• Simulator 测试；
• xcodebuild archive；
• 导出 IPA；
• 上传 App Store Connect。

这样做可以避免 macOS 节点长期执行不需要 Xcode 的任务，也能降低签名凭据暴露面。

Apple 文档给出的发布链路是：准备项目身份信息，创建 Archive，再从 Organizer 导出或上传到 App Store Connect。命令行环境可以使用 xcodebuild archive 和 xcodebuild -exportArchive 完成对应步骤。(developer.apple.com)

签名隔离建议至少分成三组：

• 普通构建账户：只能读取代码和执行非发布构建；
• 签名账户：只在需要 Archive 的 macOS 任务中使用；
• 上传凭据：使用限制范围的 App Store Connect API 密钥或专用上传流程。

不要把证书、私钥、Team ID、Bundle ID 写死在仓库里。构建脚本使用环境变量或 CI 密钥管理，并在任务结束后清理临时钥匙串。

Apple 还建议保留每个已分发构建对应的 Xcode Archive 与符号文件，否则后续崩溃诊断可能缺少必要信息。(developer.apple.com)

完成一次完整试运行后，不要只看单次编译耗时。你应该记录构建是否可复现、插件是否能回归、签名是否可撤销，以及节点重启后能否恢复。

• [ ] 从全新克隆完成前端依赖安装。
• [ ] 在 macOS 节点记录 Node.js、Xcode、CLI 和依赖管理器版本。
• [ ] 完成 npx cap sync ios，并保存日志。
• [ ] 检查 SceneDelegate.swift、Info.plist 和 AppDelegate.swift。
• [ ] 使用 Xcode 27 完成一次 Debug 构建。
• [ ] 在 Simulator 中验证冷启动、热启动、后台恢复和 URL 唤起。
• [ ] 使用至少一个真实原生插件完成回归。
• [ ] 单独验证 SPM 或现有 CocoaPods 锁定结果。
• [ ] 完成一次 Archive，并保存 .xcarchive、日志和测试结果。
• [ ] 在隔离钥匙串中验证签名，不使用开发者个人长期凭据。
• [ ] 验证上传到 App Store Connect 的流程和失败后的重试方式。
• [ ] 重启远程节点后重新执行最小构建。
• [ ] 明确真机测试由谁负责、设备放在哪里、失败如何恢复。

选择规则可以直接按条件执行：

选临时 macOS 构建环境：

• 发布频率低；
• 原生插件已经稳定；
• 主要需求是 Archive、导出和上传；
• 不需要长期保留运行中的开发节点；
• 可以接受每次重新准备环境。

选远程 Mac CI：

• 每周都有多次 iOS 构建或原生调试；
• 需要固定 Xcode、SPM 缓存和插件版本；
• 团队需要 SSH、VNC 或网页控制台持续排查问题；
• 需要保留 Archive、日志和重启恢复能力；
• 签名流程需要由团队自己控制。

保留双轨：

• UIScene 迁移尚未完全收敛；
• 社区插件适配状态还没有逐个确认；
• 一条链路用于快速发布，另一条链路用于调试和故障恢复；
• 团队还没有决定长期保留哪种签名责任边界。

低频发布时，应该怎样在两种 macOS 方案中选择？
如果只是标准化发布，临时构建环境通常更省维护工作；但如果你还要调试深链、推送、相机或自定义插件，远程 Mac 更容易保留状态和复现问题。最稳妥的做法不是凭感觉选择，而是先覆盖一次完整发布周期，再根据构建、插件、签名和重启证据决定。

继续把所有任务压在 Windows 或 Linux 上，常见缺点有三个：前端构建可以完成，但 Xcode 原生错误无法本地复现；Simulator 和图形化签名问题需要临时寻找环境；插件故障、Archive 和上传流程容易被拆成互不连续的人工步骤。

如果你已经确认需要持续执行 Capacitor iOS 构建，KVMNODE 的远程 Mac 更适合做一段完整试运行：你可以保留 macOS、Xcode、Simulator、SSH 和图形化访问链路，再根据本文的清单判断是否转为长期 CI 节点。需要先比较不同节点与使用方式时，可以查看 KVMNODE 的 Mac 租赁方案；如果你更关注 Mac mini 形态，也可以参考 Mac mini M4 租赁方案。

但如果你的团队长期高负载运行、必须接入固定物理设备，或者已有稳定的本地 Mac 资产，租赁不一定是最佳长期方案。对多数 Windows／Linux 为主、需要阶段性完成 iOS 构建和原生插件验证的团队，先租用一段能覆盖“构建—测试—归档—上传—重启恢复”的远程 Mac，再决定是否长期投入，比直接购买硬件或反复拼接临时环境更容易控制风险。