手动 iOS 构建的令人沮丧的现实
您已经花了数周时间完善您的应用。代码整洁，界面精美，您的测试用户也很满意。现在是时候推向 App Store 了。您打开 Xcode，点击“归档”，然后……什么都不起作用。构建因一个晦涩的签名错误而失败。或者构建成功了，但导出选项是错误的。或者您上传了 IPA，却收到 App Store Connect 的邮件说您的构建版本号太低。
这不是一次性问题。对于 iOS 开发者，尤其是在团队中工作或使用 CI/CD 管道的开发者来说，这是一个反复出现的噩梦。手动构建、归档、导出和上传的过程脆弱、容易出错且耗时。每一步都有其潜在的陷阱：
- 签名和描述文件不匹配：您的本地钥匙串与构建服务器的不匹配，或者描述文件一夜之间过期了。
- 版本和构建版本号冲突：其他人上传了更高版本号的构建，或者您忘记递增它。
- 导出选项混淆：应该使用自动签名还是手动签名？位码或应用瘦身呢？
- 上传失败：IPA 格式错误，或者上传超时但没有明确的反馈。
这些问题不仅浪费时间；它们会阻塞发布，导致错过最后期限，并造成不必要的压力。根本原因在于 Xcode 的命令行工具（xcodebuild）虽然强大但很复杂，而 App Store Connect 有自己的一套规则和验证。如果没有结构化的方法，您就只能在一个接一个的失败中进行调试。
一个好的解决方案应该改变什么
一个可靠的构建和上传工作流程应该做到三件事：
- 自动化重复性步骤：不再手动运行带有十几个标志的
xcodebuild命令。 - 智能处理版本控制：自动从 App Store Connect 解析下一个安全的构建版本号以避免冲突。
- 提供清晰的反馈：当出现问题时，准确告诉您出了什么问题以及如何修复。
理想情况下，这个解决方案应该与您现有的工具集成——无论您是在本地构建还是在 GitHub Actions 或 Jenkins 等 CI 环境中构建。它还应该在不要求您成为描述文件专家的情况下，遵守 Apple 的签名要求。
介绍 asc-xcode-build：一个值得检查的实用选项
如果您正在处理这些痛点，那么 asc-xcode-build 技能 值得一试。它是一个名为 app-store-connect-cli-skills 的更大工具包的一部分，该工具包为常见的 App Store Connect 任务提供命令行助手。这个特定的技能专注于构建、归档、导出和上传步骤。
重要提示：这不是一个万能药。它是一组脚本和命令，封装了 xcodebuild 和 App Store Connect API 以简化常见工作流程。您仍然需要安装 Xcode、有效的签名凭据，并且对项目结构有基本的了解。但它可以减少认知负荷并防止许多常见错误。
实践中的工作方式
该技能在 asc xcode 命名空间下提供了几个命令。以下是在典型的 iOS 发布工作流程中如何使用它：
1. 管理版本和构建版本号
在构建之前，您需要确保版本和构建版本号正确。您可以使用以下命令，而不是手动编辑 Info.plist 或 .xcconfig 文件：
asc xcode version view
asc xcode version edit --version "1.3.0" --build-number "42"
asc xcode version edit --next-build-number --app "YOUR_APP_ID" --platform IOS
--next-build-number 标志特别有用。它查询 App Store Connect 获取最新的构建版本号并递增它，防止“CFBundleVersion 太低”的错误。当多个开发者或 CI 作业上传构建时，这是一个常见的失败点。
2. 归档您的应用
您可以使用以下命令，而不是编写复杂的 xcodebuild archive 命令：
asc xcode archive \
--workspace "YourApp.xcworkspace" \
--scheme "YourApp" \
--configuration Release \
--clean \
--archive-path ".asc/artifacts/YourApp.xcarchive" \
--xcodebuild-flag=-destination \
--xcodebuild-flag=generic/platform=iOS \
--output json
此命令处理了像 --clean 这样的常见标志，并设置了统一的输出路径。--output json 标志使得在脚本中解析结果更容易。
3. 导出 IPA
归档后，您需要导出一个 IPA 用于上传。该技能可以自动生成导出选项：
asc xcode export \
--archive-path ".asc/artifacts/YourApp.xcarchive" \
--ipa-path ".asc/artifacts/YourApp.ipa" \
--xcodebuild-flag=-allowProvisioningUpdates \
--output json
如果您需要审查或自定义导出选项（例如，用于手动签名），您可以单独生成一个 plist 文件：
asc xcode export-options generate \
--archive-path ".asc/artifacts/YourApp.xcarchive" \
--output-path ".asc/ExportOptions.plist" \
--output json
4. 上传到 App Store Connect
一旦您有了 IPA，就可以直接上传：
asc builds upload --app "YOUR_APP_ID" --ipa ".asc/artifacts/YourApp.ipa" --wait
--wait 标志使命令阻塞直到 App Store Connect 完成构建的处理，这在 CI 管道中很有用，因为后续步骤依赖于构建可用。
何时使用此技能（以及何时不使用）
良好的使用场景：
- 您正在为 App Store 分发构建 iOS、tvOS、visionOS 或 macOS 应用。
- 您希望自动化版本和构建版本号管理。
- 您正在设置 CI/CD 管道，并需要可靠、可脚本化的命令。
- 您经常遇到签名或导出选项问题。
何时需要重新考虑：
- 您的项目使用了该技能标志未涵盖的高度自定义的
xcodebuild设置。在这种情况下，您可能需要回退到原始的xcodebuild命令。 - 您对命令行工具不熟悉。此技能基于 CLI，因此假设您对终端命令有一定的了解。
- 您需要管理复杂的描述文件场景（例如，企业分发）。该技能专注于 App Store Connect 工作流程。
设置和评估该技能
在将此技能集成到您的工作流程之前，请考虑以下因素：
前提条件
- Xcode 和命令行工具：必须安装在您的构建机器上。
- 签名凭据：要么在 Xcode 中启用了自动签名，要么配置了手动签名身份和描述文件。
- App Store Connect 认证：上传和版本查找命令需要此认证。这通常涉及 API 密钥或 Apple ID 凭据。
仓库信号
该技能是 app-store-connect-cli-skills 仓库 的一部分，该仓库拥有超过 900 个星标和 50 个分支。MIT 许可证允许修改和再分发。该仓库正在积极维护，主题涵盖 iOS、macOS、CI/CD 和自动化。
安全考虑
- 低安全风险：该技能不直接处理密码等敏感数据；它依赖于您现有的 Xcode 和 Apple ID 配置。
- 本地执行：命令在您的机器或 CI 服务器上运行，而不是在外部服务器上。
- 无关联：这是一个第三方工具，不是 Apple 的官方产品。
测试一下
首先在一个测试项目上运行版本查看命令：
asc xcode version view
如果它返回了您当前的版本和构建版本号，则说明该技能可以读取您的项目结构。然后在一个非生产应用上尝试 --next-build-number 命令，看看它如何解析构建版本号。
集成到您的工作流程中
如果该技能符合您的需求，您可以将其纳入您的 CI/CD 管道。例如，在 GitHub Actions 工作流程中：
- name: Build and Upload
run: |
asc xcode version edit --next-build-number --app ${{ secrets.APP_ID }} --platform IOS
asc xcode archive --workspace "YourApp.xcworkspace" --scheme "YourApp" --configuration Release --clean --archive-path ".asc/artifacts/YourApp.xcarchive" --output json
asc xcode export --archive-path ".asc/artifacts/YourApp.xcarchive" --ipa-path ".asc/artifacts/YourApp.ipa" --output json
asc builds upload --app ${{ secrets.APP_ID }} --ipa ".asc/artifacts/YourApp.ipa" --wait
这将整个构建上传过程减少到 CI 脚本中的几行。
最后的想法
构建和上传 iOS 应用不应该感觉像在雷区中行走。虽然没有任何工具能消除所有复杂性，但 asc-xcode-build 技能 为常见的痛点提供了一种结构化的方法。对于希望标准化发布流程并减少手动错误的团队来说，它特别有价值。
请记住，这是一个需要检查的工具，而不是每个项目的保证解决方案。首先在非关键应用上测试它，了解其局限性，并查看它是否符合您的工作流程。如果您厌倦了调试签名错误和版本冲突，那么它可能值得您更仔细地研究一下。