Fastlane在CircleCI上手动签名iOS应用的最佳实践

在iOS应用开发中，代码签名是一个关键但容易出错的环节。本文将详细介绍如何在使用Fastlane自动化工具时，正确配置手动代码签名流程，特别是在CircleCI这样的持续集成环境中。

问题背景

许多开发团队在使用Fastlane的match和gym工具进行iOS应用构建时，会遇到一个常见问题：虽然match成功安装了正确的证书和描述文件，但gym构建时却报告找不到匹配的描述文件。这种情况通常发生在CircleCI等CI环境中，因为默认情况下这些环境启用了自动签名机制。

核心问题分析

当Fastlane的match工具成功安装了App Store分发证书和描述文件后，理论上应该能够用于后续的构建。但在实际使用中，gym可能会报错找不到匹配的描述文件，主要原因包括：

1. Xcode项目设置中仍然启用了自动签名
2. 描述文件虽然安装但未被正确引用
3. CI环境中的临时钥匙串配置问题

解决方案

1. 禁用自动签名

在Fastlane脚本中添加一个专门用于禁用自动签名的lane：

desc "禁用自动签名并设置手动签名配置"
lane :disable_automatic_signing do
  update_code_signing_settings(
    use_automatic_signing: false,
    path: "项目名称.xcodeproj",
    team_id: ENV['FASTLANE_APPLE_TEAM_ID'],
    code_sign_identity: "iPhone Distribution",
    profile_name: "match AppStore #{ENV["APP_STORE_APP_IDENTIFIER"]}",  
  )
end

这个lane会明确地将Xcode项目设置为手动签名模式，并指定使用match安装的特定描述文件。

2. 完整的构建流程

结合上述解决方案，一个完整的TestFlight上传lane应该包含以下步骤：

lane :test_flight do
  # 1. 设置团队ID和项目配置
  team_id(ENV['FASTLANE_APPLE_TEAM_ID'])
  
  # 2. 更新版本号和显示名称
  set_info_plist_value(path: "./Info.plist", key: "CFBundleShortVersionString", value: '0.143.1')
  update_project_team(path: "项目名称.xcodeproj", teamid: ENV['FASTLANE_APPLE_TEAM_ID'])
  update_app_display_name
  
  # 3. 配置App Store Connect API密钥
  app_store_connect_api_key(
    key_id: "你的密钥ID",
    issuer_id: "你的发行者ID",
    key_filepath: "cert_key.p8"
  )
  
  # 4. 获取证书和描述文件
  match
  
  # 5. 配置钥匙串设置
  sh("security list-keychains -s ~/Library/Keychains/fastlane_tmp_keychain-db")
  unlock_keychain(path: "/Users/distiller/Library/Keychains/fastlane_tmp_keychain-db", password: "")
  sh("security set-keychain-settings -t 900 ~/Library/Keychains/fastlane_tmp_keychain-db")
  
  # 6. 关键步骤：禁用自动签名
  disable_automatic_signing
  
  # 7. 构建应用
  gym(
    scheme: "项目名称",
    export_method: "app-store",
    export_team_id: ENV['FASTLANE_APPLE_TEAM_ID'],
    xcargs: "-allowProvisioningUpdates",
    export_options: {
      method: "app-store",
      signingStyle: "manual",
      provisioningProfiles: {
        "com.example.app" => "match AppStore com.example.app"
      }
    }
  )
  
  # 8. 上传到TestFlight
  pilot(app_identifier: ENV["APP_STORE_APP_IDENTIFIER"])
end

技术要点解析

1. 钥匙串管理：在CI环境中，必须正确配置和解锁临时钥匙串，否则系统无法访问安装的证书。

2. 签名身份：明确指定"iPhone Distribution"作为代码签名身份，确保使用分发证书而非开发证书。

3. 描述文件引用：在gym的export_options中，必须精确匹配描述文件名称，这个名称可以通过match的输出或sigh manage命令查看。

4. 构建参数：添加-allowProvisioningUpdates参数允许xcodebuild在必要时更新描述文件。

最佳实践建议

1. 在本地开发环境中先测试完整的Fastlane流程，确保签名配置正确后再迁移到CI环境。

2. 为不同的环境（开发、测试、生产）使用不同的App ID和描述文件，避免混淆。

3. 定期轮换证书和描述文件，match工具可以很好地管理这个过程。

4. 在CI脚本中添加详细的日志输出，便于排查签名相关问题。

5. 考虑将签名配置作为独立的lane，便于在不同构建流程中复用。

通过以上配置，开发者可以确保在CircleCI等CI环境中可靠地使用Fastlane进行手动代码签名和应用分发，避免常见的描述文件找不到的问题。这种方案特别适合需要严格控制签名配置的企业级应用开发流程。