RetroArch 使用 fastlane 自动化构建与发布 macOS / iOS / tvOS 应用全指南【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch导读本文基于 pkg/apple/fastlane/README.md 及其背后的自动化流水线源码系统讲解 RetroArch 如何通过 fastlane 一键完成 Apple 三大平台macOS、iOS、tvOS的构建、签名与 App Store Connect / TestFlight 发布流程。读完本文你将掌握fastlane mac build、fastlane ios build、fastlane appletvos build三条 lane 的完整用法与五个可选参数的真实行为并理解版本号自动递增、Git 仓库状态管理、TestFlight 外部分发等底层实现细节可直接迁移到自己的 Apple 平台发布流程中。fastlane 在 RetroArch 项目中的角色RetroArch 的 Apple 平台构建链路分布在 pkg/apple 目录中其中 pkg/apple/fastlane 目录承载了整套自动化发布逻辑包含三个关键文件Fastfile定义全部 lane 与 private_lane是自动化流程的核心Appfile集中声明 App 标识、开发者账号与团队信息README.mdfastlane 自动生成的命令行使用文档即本文的主体文档。此外 pkg/apple/Gemfile 以 Bundler 方式固定 fastlane 依赖仅声明gem fastlane与根目录的 version.all当前版本为PACKAGE_VERSION 1.22.2共同构成版本与工具链的基础。README 开头的[bundle exec]前缀正是提示推荐通过bundle exec fastlane调用以确保使用 Gemfile 锁定的 fastlane 版本。环境准备Xcode 命令行工具与 fastlane 安装在运行任何 lane 之前需要先确保本机具备完整的命令行构建环境。README 明确要求安装最新版 Xcode 命令行工具xcode-select --install之后安装 fastlane。由于 pkg/apple/Gemfile 已存在推荐在pkg/apple目录下使用 Bundler 安装并按 README 的[bundle exec]方式调用bundle install bundle exec fastlane lane这样既能复用项目锁定的 fastlane 版本也避免污染全局 RubyGems 环境。若不用 Bundler也可直接gem install fastlane但同一台机器上多个项目对 fastlane 版本要求不一致时Bundler 方案更稳妥。三条核心 lanemac / ios / appletvosREADME 将可用操作按平台划分为 Mac、iOS、appletvos 三组每组都提供同名 lanebuild用途一致构建应用并可选上传到 App Store Connect。三条命令分别是[bundle exec] fastlane mac build [bundle exec] fastlane ios build [bundle exec] fastlane appletvos build从 Fastfile 可以看到这三个 lane 共享同一套 private_lane 流水线登录 → 重置 Git 仓库 → 更新版本 → 签名 → 构建 → 上传只是平台差异通过参数注入平台scheme关键 target / 扩展使用到的配置macRetroArch AppStore主应用OSX/Info_AppStore.plistiosRetroArch iOS ReleaseRetroArchiOS、RetroArchWidgetExtensionExtensioniOS/AppStore.xcconfigappletvosRetroArch tvOS ReleaseRetroArchTV、RetroArchTopShelfExtensioniOS/AppStore.xcconfig以 iOS 为例构建过程会通过 pkg/apple/iOS/AppStore.xcconfig 注入HAVE_APPLE_STORE、HAVE_ICLOUD、HAVE_ONLINE_UPDATER等编译宏并指定CODE_SIGN_ENTITLEMENTS与DEVELOPMENT_TEAM这正是发布版与本地调试构建的关键差异之一。五个可选参数详解README 明确说明以下参数全部可选三条 lane 的行为完全一致参数类型默认行为实际作用version字符串从version.all读取覆盖营销版本号marketing version stringdirty布尔false传true允许在 Git 工作区不干净时构建branch字符串当前分支指定构建来源分支不能与dirty同时使用upload布尔true传false阻止上传到 App Store Connectpublic布尔true传false阻止向 TestFlight 外部测试员分发仍会上传典型组合示例# 以指定版本号构建 iOS 包并正常上传、公开分发 bundle exec fastlane ios build version:1.22.3 # 允许脏工作区构建且不上传仅用于本地验证 bundle exec fastlane ios build dirty:true upload:false # 从远程分支构建并仅上传到 TestFlight 内部测试不对外分发 bundle exec fastlane appletvos build branch:release/1.22 upload:true public:falsedirty 与 branch 的源码级语义这两个参数的互斥关系直接体现在 Fastfile 的ra_reset_git_repoprivate_lane 中当dirty为true时直接跳过整个 Git 重置流程否则会执行reset_git_repo针对OSX/assets.zip、OSX/Info_AppStore.plist、assets.zip、iOS/Info.plist、tvOS/Info.plist等构建期会被改写的文件做强制重置、ensure_git_status_clean、git_pull并在传入branch时执行git checkout -b branch --track origin/branch切到指定远程分支最后打印git log -1便于日志审计。也就是说默认非 dirty路径要求工作区绝对干净并同步远程确保每次发布都基于可复现的提交。version 参数与版本号自动管理version的语义由ra_update_versionsprivate_lane 实现逻辑相当完整通过 App Store Connect 查询当前最新 TestFlight 构建号与线上版本号查询失败时分别回退到构建号45、版本1.19.1若未传version则解析仓库根目录 version.all先用正则匹配RARCH_VERSION ...匹配不到再回退到PACKAGE_VERSION ...当前仓库中生效的是PACKAGE_VERSION 1.22.2若目标版本号不高于已上架版本号由于 Apple 规则禁止对同一版本重复上传构建会自动对最后一位版本号加一如1.22.2→1.22.3最终通过update_info_plist将CFBundleVersion设为最新 TestFlight 构建号 1、CFBundleShortVersionString设为解析出的版本号写入对应平台的 Info.plist。值得注意的细节Fastfile 特意注释说明不能用agvtool统一更新版本因为仓库目录下存在多个 Xcode 工程逐 plist 写入更可靠——这解释了 README 中version参数存在的意义。底层流水线逐段剖析除了 README 明示的命令与参数Fastfile 中的 private_lane 还揭示了发布流程的真实调用链以下按执行顺序说明。1. 登录ra_appstore_login优先使用 App Store Connect API Key 方式登录。只要设置了环境变量APP_STORE_CONNECT_API_KEY_KEY_ID就会调用app_store_connect_api_key该方式还需配套设置APP_STORE_CONNECT_API_KEY_ISSUER_ID与APP_STORE_CONNECT_API_KEY_KEY_FILEPATH。若未设置则走常规账号密码登录账号与团队信息来自 Appfileapp_identifier(com.libretro.dist.RetroArch)、apple_id(libretrogmail.com)、itc_team_id与team_id。2. 更新版本ra_update_versions对应上一节所述的版本解析与 Info.plist 写入逻辑是保证每次提交构建号唯一、版本合规的关键环节。3. 更新签名ra_update_signing仅 iOS / tvOS针对 pkg/apple/RetroArch_iOS13.xcodeproj 调用update_code_signing_settings关闭自动签名显式指定iPhone Distribution签名身份、Team ID 与 profile。iOS 会同时为 Widget 扩展bundle id 为com.libretro.dist.RetroArch.RetroArchWidgetExtension配置签名tvOS 则为 Top Shelf 扩展RetroArchTopShelfExtension配置签名。4. 构建ra_build_app统一调用build_app公共参数包括workspace: RetroArch.xcworkspace多工程统一工作区derived_data_path: build/DerivedData、archive_path: build/RetroArch.xcarchiveexport_method: app-store、include_symbols: true携带符号便于崩溃分析通过export_options.provisioningProfiles按 bundle id 指定 App Store 分发 profile使用xcbeautify --renderer github-actions格式化构建日志说明该流程设计上可在 CI如 GitHub Actions中产出友好日志。5. 上传与外部分发ra_prior_build_in_review ra_upload_to_testflight当upload不为false时执行上传。先解析GIT_VERSION优先读取.git_version.h缺失时回退到last_git_commit的短哈希作为 changelog 中的提交标识Rebuild frontend for commit 。随后判断是否对外公开public默认true此时通过Spaceship::ConnectAPI查询最近 5 个构建若存在处于WAITING_FOR_REVIEW或IN_REVIEW的旧构建则自动降级为仅内部上传避免外部审查排队冲突公开分发时TestFlight 外部测试组为[Invaders, Patreons]对应项目早期的内测与赞助者渠道distribute_external: true。完整发布流程建议综合 README 与 Fastfile一次正式的 App Store 发布可遵循以下步骤安装 Xcode 命令行工具xcode-select --install在 pkg/apple 下执行bundle install安装 fastlane确认 Appfile 中的 bundle id、开发者账号与 Team ID 与自己的开发者账号匹配发布他人项目或自建流程时务必替换确认根目录 version.all 中的版本号已更新或在命令行用version:覆盖按目标平台执行对应的buildlane并按需附加dirty/branch/upload/public参数构建产物输出在build/目录archive 为build/RetroArch.xcarchive上传成功后到 App Store Connect 完成审核材料提交。相关仓库资源如需深入了解 Apple 平台的本地构建、签名与打包细节可继续阅读以下仓库内文件pkg/apple/fastlane/Fastfile本文全部 lane 与 private_lane 的源码实现pkg/apple/fastlane/Appfile账号、团队与应用标识配置pkg/apple/Gemfilefastlane 依赖声明pkg/apple/AppStore.xcconfigmacOS App Store 构建宏与签名配置pkg/apple/iOS/AppStore.xcconfigiOS/tvOS 发布构建宏配置pkg/apple/iOS/README.mdiOS 本地构建脚本构建、签名 profile、IPA 安装的补充说明version.all版本号唯一事实来源被 lane 自动解析。【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
