ios-deploy

ios-deploy

用途

此技能可自动执行 iOS 应用部署工作流，包括使用 Xcode 归档应用、上传到 TestFlight 或 App Store Connect、管理证书和配置描述文件，以及与 Fastlane 和 Xcode Cloud 等工具集成。它可简化 iOS 项目的 CI/CD 流程。

适用场景

在将 iOS 应用部署到 TestFlight 进行 Beta 测试、提交到 App Store，或在 CI 流水线中处理签名和配置时使用此技能。适用于涉及 Fastlane 自动化、Xcode Cloud 构建，或排查企业环境中证书问题的场景。

主要功能

• 使用 Xcode 命令行工具和指定的构建配置归档 iOS 应用。
• 通过 App Store Connect API 上传构建版本；此操作需要身份验证。
• 使用 Fastlane 的 match 或 sigh 操作管理证书和配置描述文件。
• 使用 Fastlane lanes 自动执行 CI 工作流，包括代码签名和 Beta 部署。
• 与 Xcode Cloud 集成，以执行基于云的构建和自动化测试。
• 通过 Spaceship API 更新 App Store 元数据，例如发行说明和截图。

使用模式

首先确保已安装 Xcode 和 Fastlane。集成 CI 时，将命令封装在脚本中，并检查 $FASTLANE_APP_ID 等环境变量。在代码变更触发构建、随后进行自动化测试和部署的流水线中使用。进行本地开发时，先交互式运行命令并验证输出，再进行自动化。请在脚本中加入错误检查，以便在失败时停止，例如在归档前确认配置描述文件是否存在。

常用命令/API

大多数任务都可使用 Fastlane；以下是执行关键操作的方法：

• 归档并构建应用：运行 xcodebuild archive -scheme MyApp -archivePath build/MyApp.xcarchive -configuration Release。接着运行 xcodebuild -exportArchive -archivePath build/MyApp.xcarchive -exportPath build/export -exportOptionsPlist exportOptions.plist。
• 上传到 TestFlight：使用 Fastlane：fastlane upload_to_testflight，并在 Fastfile 中配置：lane :beta do |options| upload_to_testflight(changelog: options[:changelog]) end。需要在环境变量中设置 $APP_STORE_CONNECT_API_KEY。
• 管理证书：运行 fastlane match development 来创建或下载配置文件；通过 Matchfile 配置 type: "development" 和 git_url: "[email protected]:user/repo.git"。
• Xcode Cloud API：通过 API 端点触发构建：向 https://api.apple.com/v1/builds 发送 POST 请求，并附带 JSON 负载 { "workflowId": "12345", "sourceBranch": "main" }；使用 $XCODE_CLOUD_TOKEN 进行身份验证。
• App Store Connect API：在 Ruby 脚本中使用 spaceship::Tunes::App.find("com.example.app") 获取应用信息：require 'spaceship'; Spaceship::Tunes.login; app = Spaceship::Tunes::App.find('bundle_id')。

集成说明

通过 gem install fastlane 将 Fastlane 添加到项目中，然后在根目录创建 Fastfile。进行身份验证时，设置 export FASTLANE_SESSION=$APP_STORE_CONNECT_API_KEY 等环境变量，以访问 App Store Connect。启用 App Store Connect 中的 Xcode Cloud，并在脚本中引用工作流 ID。对于 GitHub Actions 等 CI 工具，在 YAML 文件中添加 run: fastlane beta 等步骤，并确保已缓存依赖项。使用 Fastlane 的 lanes 处理多个环境，例如为 staging 定义一个使用不同配置描述文件的 lane。

错误处理

常见错误包括证书无效；运行 fastlane match nuke development 重置后重试。上传失败时，请使用 fastlane spaceauth -o 验证 API 密钥，并确保 bundle ID 匹配。如果归档因代码签名而失败，请运行 fastcode sign --force，并在 exportOptions.plist 中指定描述文件：<key>signingStyle</key><string>Manual</string>。在脚本中通过添加重试来处理网络错误，例如，在 bash 中：for i in {1..3}; do fastlane upload_to_testflight && break || sleep 5; done。使用 fastlane --verbose 记录输出以便调试。

具体使用示例

1. 部署到 TestFlight：在 CI 脚本中，先构建：xcodebuild -scheme MyApp -configuration Release clean build。然后上传：fastlane run upload_to_testflight api_key: $APP_STORE_CONNECT_API_KEY changelog: "Fixed bugs"。这假设 Fastfile 中已定义该 lane，且已设置环境变量。
2. 管理描述文件和归档：运行 fastlane match adhoc 获取描述文件，然后归档：xcodebuild archive -scheme MyApp -archivePath build/MyApp.xcarchive。使用以下命令导出：xcodebuild -exportArchive -archivePath build/MyApp.xcarchive -exportOptionsPlist ExportOptions.plist。可在工作流中用于 ad-hoc 分发。

图关系

• 相关：移动端集群（例如，用于跨平台部署的 android-deploy 技能）。
• 关联方式：deployment 标签（链接到 ci-cd 等通用部署技能）。
• 关联：fastlane 和 ios 标签（例如，关联 fastlane 专用工具和其他 iOS 技能）。
• 依赖项：appstore 标签表示需要与处理 API 密钥和身份验证的技能集成。