如何通过Github Actions+Fastlane将Flutter macOS应用上传至TestFlight？

核心思路 #

TestFlight 接受 macOS 应用的 .xcarchive 归档文件或 .pkg 安装包，因此需要先将 Flutter 生成的 .app 文件转换为这两种格式之一，再通过 Fastlane 上传。

步骤1：构建Flutter macOS Release应用 #

在 GitHub Actions 中执行构建命令，生成签名后的 .app 文件：

flutter build macos --release

构建完成后，.app 文件默认路径为：build/macos/Build/Products/Release/Runner.app

步骤2：将.app转换为TestFlight支持的格式 #

有两种常用方式可选：

方式A：生成Xcode归档文件（.xcarchive）

使用 xcodebuild 命令创建归档，这是最贴合Apple生态的方式：

xcodebuild archive \
  -workspace macos/Runner.xcworkspace \
  -scheme Runner \
  -configuration Release \
  -archivePath build/macos/Runner.xcarchive

注意：需确保项目已配置好 macOS 应用的签名证书与 Provisioning Profile，或使用 Apple API Key 完成认证。

方式B：打包为.pkg安装包

使用 productbuild 命令将 .app 打包成标准安装包：

productbuild --component build/macos/Build/Products/Release/Runner.app /Applications build/macos/Runner.pkg

步骤3：编写Fastlane脚本上传 #

修改 macos/fastlane/Fastfile，新增 macOS 分发 lane：

desc "Upload macOS app to TestFlight"
lane :distribute_macos do
  # 若已在GitHub Actions中执行flutter build，可注释此行
  # sh "flutter build macos --release"

  # 方式A：上传.xcarchive（二选一即可）
  upload_to_testflight(
    api_key: api_key,
    package_path: "../build/macos/Runner.xcarchive",
    skip_waiting_for_build_processing: true
  )

  # 方式B：上传.pkg（二选一即可）
  # upload_to_testflight(
  #   api_key: api_key,
  #   package_path: "../build/macos/Runner.pkg",
  #   skip_waiting_for_build_processing: true
  # )
end

步骤4：配置GitHub Actions工作流 #

创建 .github/workflows/macos-testflight.yml，示例配置如下：

name: Upload macOS App to TestFlight

on:
  push:
    branches: [ main ]

jobs:
  build-and-upload:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.13.x' # 替换为你的Flutter版本
          channel: 'stable'
          
      - name: Install dependencies
        run: flutter pub get
        
      - name: Build macOS Release
        run: flutter build macos --release
        
      - name: Create Xcode Archive
        run: |
          xcodebuild archive \
            -workspace macos/Runner.xcworkspace \
            -scheme Runner \
            -configuration Release \
            -archivePath build/macos/Runner.xcarchive
            
      - name: Set up Fastlane
        run: |
          cd macos
          bundle install
          
      - name: Upload to TestFlight
        env:
          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
          APPLE_API_KEY_ISSUER_ID: ${{ secrets.APPLE_API_KEY_ISSUER_ID }}
          APPLE_API_KEY: ${{ secrets.APPLE_API_KEY }}
        run: |
          cd macos
          fastlane distribute_macos

注意：需在 GitHub 仓库的 Secrets 中配置 Apple API Key 相关参数，用于认证。

内容的提问来源于stack exchange，提问作者Adam Zarn