如何通过Bitbucket Pipeline实现iOS构建生成与TestFlight自动上传

一、环境与前置准备 #

• 选用Bitbucket支持iOS构建的镜像：比如macos-xcode-14（需匹配你的Xcode版本需求），该镜像预装Xcode、Homebrew等必要工具。
• 准备iOS签名资产：
  • 分发证书（.p12格式）：从Apple开发者后台导出，设置证书密码。
  • App Store分发配置文件（.mobileprovision）：对应你的App Bundle ID，从开发者后台下载。
  • App Store Connect API密钥（.p8）：在App Store Connect的「用户与访问」-「密钥」中创建，记录密钥ID和Issuer ID，确保密钥拥有「App Manager」权限。
• 把上述文件上传到Bitbucket仓库的「Secure Files」中，同时在仓库「Repository Variables」中配置敏感信息：KEYCHAIN_PASSWORD（自定义钥匙链密码）、CERT_PASSWORD（证书导出密码）、API_KEY_ID、ISSUER_ID。

二、Pipeline配置示例 #

以下是完整的bitbucket-pipelines.yml配置：

image: macos-xcode-14
pipelines:
  default:
    - step:
        name: 构建并上传iOS至TestFlight
        caches:
          - flutter
        script:
          # 安装稳定版Flutter
          - git clone https://github.com/flutter/flutter.git -b stable --depth 1
          - export PATH="$PATH:`pwd`/flutter/bin"
          - flutter doctor -v
          
          # 安装Flutter依赖
          - flutter pub get
          
          # 生成无签名的iOS归档
          - flutter build ios --release --no-codesign
          
          # 下载签名资产
          - pipe: atlassian/secure-file-download:0.1.1
            variables:
              SECURE_FILE: "ios_distribution.p12"
              LOCAL_PATH: "ios/ios_distribution.p12"
          - pipe: atlassian/secure-file-download:0.1.1
            variables:
              SECURE_FILE: "AppStore_Profile.mobileprovision"
              LOCAL_PATH: "ios/AppStore_Profile.mobileprovision"
          - pipe: atlassian/secure-file-download:0.1.1
            variables:
              SECURE_FILE: "AuthKey_XXXXXX.p8"
              LOCAL_PATH: "ios/AuthKey_XXXXXX.p8"
          
          # 配置签名钥匙链
          - security create-keychain -p $KEYCHAIN_PASSWORD build.keychain
          - security default-keychain -s build.keychain
          - security unlock-keychain -p $KEYCHAIN_PASSWORD build.keychain
          - security import ios/ios_distribution.p12 -k build.keychain -P $CERT_PASSWORD -T /usr/bin/codesign
          # 修复签名权限问题
          - security set-key-partition-list -S apple-tool:,apple: -s -k $KEYCHAIN_PASSWORD build.keychain
          
          # 安装配置文件
          - mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
          - cp ios/AppStore_Profile.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/
          
          # 用Xcode完成签名并导出IPA
          - xcodebuild -workspace ios/Runner.xcworkspace -scheme Runner -configuration Release -archivePath build/ios/archive/Runner.xcarchive archive
          - xcodebuild -exportArchive -archivePath build/ios/archive/Runner.xcarchive -exportPath build/ios/ipa -exportOptionsPlist ios/ExportOptions.plist
          
          # 上传至TestFlight
          - xcrun altool --upload-app -f build/ios/ipa/Runner.ipa -t ios --apiKey $API_KEY_ID --apiIssuer $ISSUER_ID --apiKeyPath ios/AuthKey_XXXXXX.p8
        artifacts:
          - build/ios/ipa/*.ipa
        variables:
          KEYCHAIN_PASSWORD: $KEYCHAIN_PASSWORD
          CERT_PASSWORD: $CERT_PASSWORD
          API_KEY_ID: $API_KEY_ID
          ISSUER_ID: $ISSUER_ID

三、关键配置说明 #

1. ExportOptions.plist：放在iOS项目根目录，配置签名方式和分发类型，示例如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store</string>
    <key>signingStyle</key>
    <string>manual</string>
    <key>provisioningProfiles</key>
    <dict>
        <key>com.your.app.bundleid</key>
        <string>你的App Store配置文件名称</string>
    </dict>
</dict>
</plist>

2. 缓存优化：启用Flutter缓存可以加快后续构建速度，避免重复下载Flutter SDK和依赖。

四、常见问题排查 #

• 签名失败：检查证书与配置文件的Bundle ID是否匹配；确认security set-key-partition-list命令已执行，该命令用于授予codesign工具访问证书的权限。
• 上传TestFlight失败：检查API密钥的权限是否为「App Manager」；确认Issuer ID、Key ID与密钥文件对应；若遇到网络问题，可添加--verbose参数查看详细日志。
• Flutter构建错误：确保Flutter SDK版本与Xcode版本兼容（比如Flutter 3.7+建议搭配Xcode 14+）；执行flutter clean后重新构建。

内容的提问来源于stack exchange，提问作者Sachin Aphro ECS