Fastlane上传TestFlight构建时出现重复构建问题的分析与解决方案

问题现象

近期在使用Fastlane工具上传iOS应用到TestFlight时，许多开发者遇到了一个相同的问题：系统报告"Found more than 1 matching build"错误，显示有两个相同版本号(如4.3.0(1259))的构建处于PROCESSING状态。这个问题从2024年9月26日开始集中出现，影响了多个开发团队的正常构建流程。

问题本质分析

这个问题的核心在于Fastlane的构建监控机制(BuildWatcher)在检查App Store Connect上的构建状态时，发现有两个完全相同的构建版本处于处理中状态，导致系统无法确定应该跟踪哪一个构建的进度。正常情况下，每个版本号+构建号的组合应该是唯一的。

可能的原因

根据开发者社区的反馈和分析，这个问题可能有以下几个原因：

1. Apple服务端问题：可能是App Store Connect近期更新后出现的接口异常，导致构建状态查询返回了重复结果。

2. 版本号格式问题：多位开发者注意到出现问题的版本号大多以".0"结尾(如7.4.0、1.33.0等)，这可能触发了某种系统bug。

3. 并行处理机制：TestFlight的构建处理系统可能在某种情况下会创建重复的处理任务。

已验证的解决方案

方案一：修改版本号格式

多位开发者验证有效的临时解决方案是修改版本号，避免以".0"结尾：

1. 将原本计划的版本号如7.4.0改为7.4.1
2. 将1.33.0改为1.33.1
3. 即使是首个版本，也可以使用1.0.1而非传统的1.0.0

这个方案的优势是简单直接，但缺点是可能需要调整版本号规划策略。

方案二：分步上传和分发

另一个有效的解决方案是将上传和分发操作分开进行：

1. 第一次调用upload_to_testflight仅上传IPA，忽略分发错误
2. 第二次调用添加distribute_only: true参数完成分发

示例代码：

# 第一步：仅上传
upload_to_testflight(
  ipa: ENV["IPA_PATH"],
  skip_waiting_for_build_processing: true
)

# 第二步：仅分发
upload_to_testflight(
  distribute_only: true,
  app_version: ENV["APP_VERSION"],
  build_number: ENV["BUILD_NUMBER"]
)

方案三：手动处理

如果自动化流程完全受阻，开发者也可以考虑：

1. 使用Fastlane仅完成IPA上传
2. 登录App Store Connect手动完成测试分发
3. 等待Apple修复问题后再恢复全自动化流程

问题影响范围

这个问题影响了Fastlane的多个版本，包括但不限于2.220.0版本。它不仅导致构建流程失败，还可能影响以下功能：

1. 自动上传的构建变更日志(changelog)无法显示
2. 本地化构建信息(localized_build_info)可能丢失
3. CI/CD流程中断

开发者建议

1. 如果使用CI/CD系统，建议暂时添加错误处理逻辑，允许构建上传成功但分发失败的情况。

2. 密切关注Fastlane官方更新，这个问题很可能会在后续版本中得到修复。

3. 对于关键版本发布，考虑使用修改版本号的方法确保流程顺利进行。

4. 记录构建状态，以便在问题解决后分析影响范围。

技术原理深入

Fastlane的构建监控机制是通过App Store Connect API查询特定版本号和构建号的构建状态。当API返回多个相同版本的构建记录时，Fastlane的保护机制会主动报错，避免后续操作可能导致的不可预期行为。这原本是一个健壮性设计，但在当前的服务端异常情况下反而成为了障碍。

总结

这个问题的出现提醒我们，即使在成熟的工具链和平台上，也可能因为服务端变化而出现意外情况。开发者需要掌握多种解决方案，并根据项目实际情况选择最适合的临时应对措施。同时，保持对工具链更新的关注，以便在官方修复后及时升级。