Unity 的 Xcode 自动化打包全攻略

适用版本：Unity 2021.3 LTS+、Xcode 14+、macOS 12+。CI 示例基于 GitHub Actions，亦可迁移到 Jenkins、GitLab CI 或 Bitrise。

前言

手动点开 Unity → Build iOS → 打开 Xcode → Archive → Export IPA？
开发迭代一多，这套流程就成了生产力杀手。借助 命令行导出 + xcodebuild + fastlane，配合 CI 服务，可做到 推送代码 ➜ 自动出包 ➜ TestFlight，安卓端亦可对称实现，真正一键全平台。

环境准备

工具	版本	作用
macOS	12+	Runner 环境
Unity Hub	3.7+	管理 Unity 版本
Unity Editor	2021.3 LTS+	支持 CLI 构建
Xcode	14+	iOS 16 兼容
fastlane	≥ 2.220	自动签名、上传 TestFlight
Apple Developer 账号	企业/个人	证书 & 描述文件

注意：CI 服务器需安装 Xcode Command Line Tools：
xcode-select --install

Unity CLI 导出 Xcode 工程

脚本路径：Assets/Editor/CI/BuildiOS.cs

using UnityEditor;
using UnityEditor.Build.Reporting;
using UnityEngine;

public class BuildiOS
{
    static string[] Scenes => new[] { "Assets/Scenes/Boot.unity", "Assets/Scenes/Main.unity" };

    public static void Build()
    {
        string buildPath = "Build/iOS";
        BuildPlayerOptions opts = new()
        {
            scenes = Scenes,
            locationPathName = buildPath,
            target = BuildTarget.iOS,
            options = BuildOptions.CompressWithLz4HC
        };

        BuildReport report = BuildPipeline.BuildPlayer(opts);
        if (report.summary.result != BuildResult.Succeeded)
        {
            Debug.LogError($"iOS build failed: {report.summary.result}");
            EditorApplication.Exit(1);
        }
    }
}

CLI 调用

/Applications/Unity/Hub/Editor/2021.3.40f1/Unity   -batchmode -quit   -projectPath "$PWD"   -executeMethod BuildiOS.Build   -logFile build_ios.log

输出目录即为标准 Xcode 工程：Build/iOS/Unity-iPhone.xcworkspace

xcodebuild 签名与 IPA 打包

xcodebuild   -workspace Build/iOS/Unity-iPhone.xcworkspace   -scheme Unity-iPhone   -configuration Release   -archivePath Build/iOS/Build.xcarchive   clean archive   DEVELOPMENT_TEAM="YOUR_TEAM_ID"   PROVISIONING_PROFILE_SPECIFIER="iOS_Distribution"

# 导出 IPA
xcodebuild -exportArchive   -archivePath Build/iOS/Build.xcarchive   -exportOptionsPlist ci/ExportOptions.plist   -exportPath Build/iOS/IPA   -allowProvisioningUpdates

ExportOptions.plist 关键字段：method: app-store、uploadBitcode: NO、manageAppVersionAndBuildNumber: YES
证书与描述文件推荐使用 App Store Connect API Key + fastlane match 管理

Fastlane 分步自动化

在 ios/fastlane/Fastfile：

default_platform(:ios)

platform :ios do
  desc "构建并上传 TestFlight"
  lane :ci do
    build_app(
      workspace: "Build/iOS/Unity-iPhone.xcworkspace",
      scheme: "Unity-iPhone",
      export_options: "ci/ExportOptions.plist",
      output_directory: "Build/iOS/IPA",
      clean: true
    )
    upload_to_testflight
  end
end

本地验证：

bundle install   # 安装 fastlane
fastlane ios ci  # 执行 lane

GitHub Actions 完整流水线

.github/workflows/ios.yml

name: iOS CI

on:
  push:
    branches: [ main ]

jobs:
  build-ios:
    runs-on: macos-13
    steps:
      - uses: actions/checkout@v4

      - name: Setup Unity
        uses: game-ci/unity-builder@v3
        with:
          unityVersion: 2021.3.40f1
          targetPlatform: iOS

      - name: Build Xcode
        run: |
          chmod +x ./ci/build_unity_ios.sh
          ./ci/build_unity_ios.sh

      - name: Install fastlane
        run: sudo gem install fastlane -NV

      - name: Fastlane upload
        run: fastlane ios ci
        env:
          FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD: ${{ secrets.APP_SPECIFIC_PW }}
          FASTLANE_API_KEY_JSON: ${{ secrets.APP_STORE_API_KEY }}

安全提示：

APP_SPECIFIC_PW 为 Apple ID 专用密码

APP_STORE_API_KEY 存储 API Key JSON，由 fastlane 读取

常见坑与排查

症状	可能原因	解决方案
`archive failed with exit code 65`	证书/描述文件不匹配	检查 `DEVELOPMENT_TEAM` 与 profile
`No signing certificate "*iOS Distribution"`	Runner 钥匙串缺证书	fastlane match / 手动导入
`bitcode bundle could not be generated`	Xcode 14 默认关闭 Bitcode	`uploadBitcode: NO`
上传 TestFlight 卡 0%	Upload API Token 权限不足	重新生成 App Manager 角色 Key

结语

现在，只需 git push，云端就能自动生成 IPA 并推送至 TestFlight，开发、测试、产品立即可装包体验。把同样思路推广到 Android (Gradle) 与 PC (SteamPipe)，真正实现多平台快速交付。祝你的流水线稳定高效、版本飞速迭代！

附录 · 关键脚本

ci/build_unity_ios.sh —— Unity CLI 导出 + xcodebuild 脚本
ci/ExportOptions.plist —— IPA 导出配置
ios/fastlane/Fastfile —— TestFlight 上传 Lane

如需完整脚本或遇到任何问题，欢迎留言讨论。

Last modified on 2025-06-09