fastlane gym 如何配置 ad-hoc 导出方法生成企业内部分发包-育师

fastlane gym 如何配置 ad-hoc 导出方法生成企业内部分发包

【免费下载链接】fastlane🚀 The easiest way to automate building and releasing your iOS and Android apps项目地址: https://gitcode.com/GitHub_Trending/fa/fastlane

如果你的 iOS 应用不经过 App Store 或 TestFlight，而是直接以 ipa 形式分发给公司内部测试人员或员工，就需要用export_method ad-hoc让 Xcode 按 ad-hoc 方式签名并导出归档。fastlane 的gym（即build_appaction）封装了xcodebuild archive和xcodebuild -exportArchive两步操作，只要指定--export_method ad-hoc就能生成签名好的 ipa 文件。本文基于仓库内 gym 文档和 gym 选项定义，说明从命令行到Gymfile的完整配置方式，以及如何确认 ipa 已正确生成。

export_method 的可选值与 ad-hoc 的适用位置

export_method决定了归档导出时使用的签名方式，可选值（来自 options.rb 的定义）为：

app-store, validation, ad-hoc, package, enterprise, development, developer-id and mac-application

上传 App Store / TestFlight 时使用app-store；
分发给已知设备的企业内部测试包使用ad-hoc，这是本文的目标；
enterprise是另一个独立取值，适用于企业证书场景，本文不涉及。

主路径：命令行直接指定 ad-hoc

在项目根目录执行：

fastlane gym

默认构建应用。要改用 ad-hoc 导出，加上--export_method：

fastlane gym --export_method ad-hoc

指定 workspace 与 scheme 的完整形式（--clean表示构建前清理）：

fastlane gym --workspace "Example.xcworkspace" --scheme "AppName" --clean --export_method ad-hoc

布尔参数写成参数名 true/false的形式，例如同时关闭 symbols 并开启 bitcode：

fastlane gym --export_method ad-hoc --include_bitcode true --include_symbols false

查看gym全部可用参数：

fastlane action gym

如果项目不在默认 Xcode 下，可用环境变量切换：

DEVELOPER_DIR="/Applications/Xcode6.2.app" fastlane gym

用 Gymfile 固化配置

每次手写参数不方便时，把默认值存进Gymfile。先运行初始化命令：

fastlane gym init

文档给出的示例Gymfile（注意output_name只写文件名，gym会自动补.ipa后缀，带.ipa的写法会被自动去掉）：

scheme("Example") sdk("iphoneos9.0") clean(true) output_directory("./build") # store the ipa in this folder output_name("MyApp") # the name of the ipa file

在 Gymfile 中配置 ad-hoc 导出选项

自 Xcode 7 起，gym通过 Xcode 的导出选项 plist 机制工作：默认它替你创建这个 plist，并暴露export_method、export_team_id、include_symbols、include_bitcode几个参数供修改。需要更多选项时，在Gymfile里直接传 hash：

export_options({ method: "ad-hoc", manifest: { appURL: "https://example.com/My App.ipa", }, thinning: "<thin-for-all-variants>" })

也可以指向一个自己维护的 plist 文件，gym会读取并把 key 转成符号使用：

export_options("./ExportOptions.plist")

plist 中的完整可选项用xcodebuild -help查看。另有两个与导出相关的常用参数：

export_team_id：文档描述为“Sometimes you need to specify a team id when exporting the ipa file”，多个团队账号环境下指定导出用团队；
include_symbols/include_bitcode：控制 ipa 是否包含符号与 bitcode。

Xcode 9 之后的描述文件映射

从 Xcode 9 开始，导出需要明确指定每个 app target 使用哪个 provisioning profile。gym会先尝试从工程里自动探测这份 bundle id 到 profile 名称的映射（见 detect_values.rb）；探测不到且未提供时，会在 Xcode 9 及以上直接报错提示需要显式映射。

自动探测失败时，按 build_app 文档给出的方式手动传映射（bundle identifier → profile 名称）：

build_app( scheme: "Release", export_method: "ad-hoc", export_options: { provisioningProfiles: { "com.example.bundleid" => "Provisioning Profile Name" } } )

文档特别指出：如果 fastlane 与match一起使用，不需要手动提供这份映射，除非你通过export_options传入了 plist 文件路径。此外，build_app action 在 lane 运行时还会自动处理两类映射注入：lane 中sigh产生的 profile 会按其 bundle id 写入provisioningProfiles；若之前未显式指定export_method且sigh使用的不是 development 类型，export_method会自动取sigh的 profile 类型。在 fastlane lane 里调用gym(scheme: "MyApp")时这些逻辑同样生效。

验证构建结果

gym完成导出的流程是：先xcodebuild archive并校验归档，再调用xcrun ... -exportArchive -exportOptionsPlist ...导出签名 ipa，然后把产物移动到output_directory（默认当前目录.）。成功的判定方式如下（来自 runner.rb 与实际输出文案）：

终端出现Successfully exported and signed the ipa file:，下一行打印 ipa 绝对路径。例如output_directory为./build、output_name为MyApp时，产物位于./build/MyApp.ipa（路径为运行输出，非固定示例值）。
同目录下会生成压缩的 dSYM 文件MyApp.app.dSYM.zip，导出文案为Successfully exported and compressed dSYM file。
若指定了export_options的 manifest 等选项，导出时产生的manifest.plist也会被一并移入输出目录并打印路径。
在 fastlane lane 中使用gym/build_app时，action 返回 ipa 的绝对路径，并可读取IPA_OUTPUT_PATH（gym的gym(scheme: ...)返回值可直接用于后续分发 action）。
归档本身会存入 Xcode Organizer，构建结束会提示Successfully stored the archive. You can find it in the Xcode Organizer.。

gym的运行界面与输出效果可参考文档中的截图：

排查问题与已知限制

查看详细过程：fastlane gym --verbose打开 verbose 模式，会额外打印Generated Build Command/Generated Package Command的完整参数表（见 runner.rb 中print_command的逻辑）。
原始 xcodebuild 日志：打开~/Library/Logs/gym查看未经 xcpretty 格式化的原始输出。
构建或导出失败：失败信息会经ErrorHandler处理，lane 中可通过error do |lane, exception|捕获，exception.error_info包含进程输出，适合转发给 Slack 等工具。
ad-hoc 与 enterprise 是两种导出方式，export_method的校验逻辑会拒绝列表之外的取值（如Unsupported export_method 'xxx'），配置内部测试包时确认为ad-hoc而不是拼写其他值。
若你传了 plist 路径而不是 hash，gym不会替你注入sigh/match的 profile 映射，此时需要自己在 plist 中写清 profile 信息（build_app会打印一条 Xcode 9 相关提醒）。