企业官网建设流程全解析

fastlane 多语言 Android 截图示例工程全解：从 Fastfile 车道配置到 screengrab 自动化落地

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

本文以 fastlane 仓库中screengrab官方示例工程（localetester）所自动生成的 screengrab/example/fastlane/README.md 为骨架，结合其 Fastfile、Appfile、Screengrabfile 与 screengrab 源码，系统讲解如何为 Android 应用编排「单元测试 → 构建 → 分发 → Google Play 发布 → 多语言截图采集」的完整自动化车道，并深入到capture_android_screenshots的底层实现与仪器测试写法。读完你将能看懂并复刻一套可运行的多语言截图流水线。

一、这份 README 是什么：fastlane 自动生成的 Lane 文档

先要厘清文件的性质：screengrab/example/fastlane/是 screengrab 为演示多语言截图而内置的一个完整 Android 示例工程localetester的 fastlane 配置目录。其中这份 README.md 并非手工维护的用户手册，而是 fastlane 官方文档生成器的产物——文件末尾明确指出：

This README.md is auto-generated and will be re-generated every timefastlaneis run.

也就是说，只要在包含该 Fastfile 的目录下运行一次fastlane，fastlane 就会扫描当前 Fastfile 中定义的平台与 lane，自动把每个 lane 的desc、可执行命令等重新生成为这份 README。因此它天然是对该工程全部 lane 的权威「命令清单」，也是最真实的入门示例：README 中列出的每一条 lane，都能在 Fastfile 源码里找到一一对应的定义。

二、环境准备：在 macOS 上安装 fastlane

原 README 开篇给出的是 fastlane 的标准安装流程（注意：示例工程虽然是 Android 应用，但 fastlane 工具链本身的历史形态要求 Xcode 命令行工具作为构建依赖，因此在 macOS 上仍要先完成这一步）。

首先确保安装了最新版 Xcode 命令行工具：

xcode-select --install

随后通过 RubyGems 安装 fastlane（必要时加sudo，-NV表示不打印冗余安装日志、跳过安装后文档生成，能显著提速）：

[sudo] gem install fastlane -NV

或通过 Homebrew 安装：

brew install fastlane

安装完成后，可在任意包含Fastfile的目录中执行fastlane actions、fastlane lanes等命令列出可用 action 与 lane；本示例工程则可以直接运行fastlane android <lane名>。

三、示例工程的 fastlane 配置目录结构

screengrab/example/fastlane/目录下共有四个文件，职责非常清晰：

配套的示例 Android 工程位于 screengrab/example/：根目录提供 Gradle Wrapper（gradlew），src/androidTest 下存放了真正执行截图动作的仪器测试，src/main则是被测试的多语言演示应用（含values-fr-rFR、values-ja-rJP等多语言资源）。

四、Appfile：声明应用包名

Appfile 内容极简，仅一行：

package_name "tools.fastlane.localetester"

它把 Android 应用包名tools.fastlane.localetester登记为 fastlane 的全局配置。根据 screengrab 参数解析源码 options.rb，app_package_name的默认值正是通过CredentialsManager::AppfileConfig.try_fetch_value(:package_name)从 Appfile 读取——所以后续 screengrab 运行时即使不在命令行显式传包名，也能自动识别被测应用。

五、Fastfile：逐条拆解五个 Android lane

Fastfile 是整份 README 的命令来源。文件开头先声明最低版本fastlane_version("1.46.1")，并通过default_platform(:android)把默认平台设为 Android（platform(:android)内定义的所有 lane 因此可直接以fastlane android xxx调用）。

1.android test—— 运行全部单元测试

lane(:test) do gradle(task: "test") end

等价命令fastlane android test。这条 lane 通过 gradle action 执行 Gradle 的test任务，把 JVM 侧单元测试接入 fastlane 流程。

2.android beta—— 提交 Crashlytics Beta

lane(:beta) do gradle(task: "assembleRelease") crashlytics end

先构建 Release 包，再调用crashlyticsaction 把构建产物上传到 Crashlytics Beta 进行内测分发。Fastfile 中的注释也提示可以替换为其他 Beta 测试服务，或用sh "your_script.sh"执行自定义脚本。

3.android deploy—— 发布到 Google Play

lane(:deploy) do gradle(task: "assembleRelease") supply end

supply即仓库 supply 模块的 action，负责上传 APK 与元数据到 Google Play。这条 lane 是「构建 + 上架」的最小闭环。

4.android assemble—— 构建调试包与测试 APK

lane(:assemble) do gradle(task: "assemble assembleAndroidTest", gradle_path: '../gradlew') end

这里特别指定了gradle_path: '../gradlew'，因为示例工程的 Gradle Wrapper 位于 screengrab/example/gradlew，相对 fastlane 配置目录需回退一级。任务assemble assembleAndroidTest同时产出 App 调试 APK 与被测工程专用的 androidTest APK——这正是 screengrab 截图所需的两个 APK。

5.android build_and_screengrab—— 一键产出多语言截图（核心 lane）

lane(:build_and_screengrab) do gradle(task: "assembleDebug assembleAndroidTest") capture_android_screenshots end

这是本示例最关键的 lane：先由 Gradle 构建assembleDebug（App 调试包）与assembleAndroidTest（androidTest 测试包），随后调用capture_android_screenshotsaction 启动 screengrab 完成多语言截图采集。README 中对应条目 "Build debug and test APK for screenshots" 即描述该流程。screengrab 具体截哪些语言、用哪个 APK，则由 Screengrabfile 决定（见下节）。

此外 Fastfile 还演示了全局 hooks 的用法：before_all在每个 lane 前执行（默认注释掉 SLACK_URL 配置）、after_all在 lane 成功后回调、error在 lane 抛异常时回调（均预留了 Slack 通知的模板），构成一套带生命周期钩子的完整自动化编排。

六、Screengrabfile：控制多语言与截图输入

capture_android_screenshots不带任何参数调用，是因为截图参数都收敛到了 Screengrabfile：

locales ['en-US', 'fr-FR', 'ja-JP'] clear_previous_screenshots true tests_apk_path 'build/outputs/apk/androidTest/debug/example-debug-androidTest.apk' app_apk_path 'build/outputs/apk/debug/example-debug.apk'

结合 screengrab 的参数定义源码 options.rb，可得到各参数的行为与默认值：

• locales：声明需要采集的语言列表，即 README 中多语言截图的来源。默认值为['en-US']（options.rb#L27-L31）。screengrab 会通过LocaleTestRule逐一切换被测 App 的语言环境并截图。
• clear_previous_screenshots：设为true时，在截图前自动清空输出目录中旧截图，保证产出干净（对应环境变量SCREENGRAB_CLEAR_PREVIOUS_SCREENSHOTS，默认false）。
• app_apk_path/tests_apk_path：分别指定被测 App 与 androidTest 测试包的 APK 路径。源码对二者都注册了verify_block，若路径下找不到文件会直接以UI.user_error!报错退出（options.rb#L94-L115），因此在本地复现时需确保路径与 Gradle 实际产物一致。
• 未被本文件覆盖但有源码级默认值的常用项：output_directory默认fastlane/metadata/android（即截图输出目录，可由SCREENGRAB_OUTPUT_DIRECTORY覆盖）；tests_package_name缺省时为"#{app_package_name}.test"，即示例中tools.fastlane.localetester.test，见 detect_values.rb；test_instrumentation_runner默认为androidx.test.runner.AndroidJUnitRunner。

仓库还提供了带注释的可复制模板 ScreengrabfileTemplate，并注明所有可选项可用fastlane screengrab --help查看。

七、capture_android_screenshots：一条 lane 背后的调用链

当 Fastfile 执行到capture_android_screenshots时，实际进入的是 action 定义 fastlane/lib/fastlane/actions/capture_android_screenshots.rb，其核心流程为：

Screengrab.config = params Screengrab.android_environment = Screengrab::AndroidEnvironment.new(params[:android_home], params[:build_tools_version]) Screengrab::DependencyChecker.check(Screengrab.android_environment) Screengrab::Runner.new.run Actions.lane_context[SharedValues::SCREENGRAB_OUTPUT_DIRECTORY] = File.expand_path(params[:output_directory])

拆开来看：

1. Screengrab.config = params将 fastlane 层参数（含来自 Screengrabfile 的合并结果）注入 screengrab 模块；
2. AndroidEnvironment基于android_home与build_tools_version构造 Android SDK 环境信息（android_home缺省从ANDROID_HOME/ANDROID_SDK_ROOT/ANDROID_SDK环境变量读取，见 options.rb#L15-L21）；
3. DependencyChecker.check在运行前校验 adb、aapt 等外部依赖是否齐备（实现见 dependency_checker.rb）；
4. Runner.new.run驱动整条截图管线（runner.rb）：按locales启动/复用模拟器、安装两个 APK、依次以每个 locale 运行仪器测试并抓取屏幕；
5. 最后把展开后的输出目录写入lane_context[:SCREENGRAB_OUTPUT_DIRECTORY]，供后续 lane 通过共享值读取截图产物路径。

另外，action 还定义了别名：在 fastlane/lib/fastlane/actions/screengrab.rb 中ScreengrabAction < CaptureAndroidScreenshotsAction，因此capture_android_screenshots与screengrab写法完全等价（该 action 的is_supported?仅对:android平台返回 true，见 capture_android_screenshots.rb#L41-L43）。

八、截图从哪来：示例中的仪器测试代码

流水线跑起来后，真正负责「在正确的语言环境里对正确页面按下快门」的是 Android 仪器测试 FalconScreenshots.java。这个测试类演示了 screengrab 客户端库（screengrab-lib）的三种关键用法：

• @ClassRule LocaleTestRule：作为类级规则，它会在一次测试运行中自动遍历 Screengrabfile 里声明的所有locales（en-US、fr-FR、ja-JP），每切换一个语言环境就重跑一遍测试方法，从而让同一个Screengrab.screenshot(...)调用产出各语言版本的截图；
• FalconScreenshotStrategy：通过Screengrab.setDefaultScreenshotStrategy(new FalconScreenshotStrategy(activity))指定截图实现。Falcon 是基于截图合成的高性能策略，无需 root，适合大部分 UI 截图场景；
• Screengrab.screenshot("falcon_beforeFabClick")：在 UI 交互的关键节点（点击 FAB 前、跳转到AnotherActivity、弹出对话框后）显式截图。截图名称会与 locale 结合，最终落入对应语言的输出子目录，例如en-US/images/...、fr-FR/images/...。

配合 Espresso 的onView(...).check(matches(isDisplayed()))等断言，示例同时演示了「截图前先等待/校验 UI 就绪」的规范姿势；同目录下的 JUnit4StyleTests.java 则展示了另一套截图测试的组织风格。

九、README 中 lane 清单的复现与自检

依照原 README，示例工程共暴露五个 Android lane，全部可独立执行：

fastlane android test # 运行全部单元测试 fastlane android beta # 提交 Crashlytics Beta fastlane android deploy # 发布到 Google Play（需 supply 相关凭证） fastlane android assemble # 构建 debug App 与 androidTest APK fastlane android build_and_screengrab # 构建并采集多语言截图

需要说明的适用前提：前三条 lane 依赖对应的外部服务（Crashlytics、Google Play Console）与凭证，纯本地验证时建议从android assemble或android build_and_screengrab入手；后者还要求本机存在 Android SDK、可用的模拟器/真机以及 adb。若截图产物目录被清空或重复写入，请核对output_directory（默认fastlane/metadata/android）与 Screengrabfile 中两个 APK 路径是否与 Gradlebuild/outputs的实际输出一致——源码会在 APK 缺失时直接报错提示。

十、延伸阅读与证据索引

围绕本文涉及的环节，可继续在仓库中深入以下实现：

• Lane 文档生成机制：runner.rb 及 fastlane 的 lane 列表/文档生成逻辑；
• gradle action：gradle.rb，支持task、gradle_path等参数；
• screengrab 主流程与参数：runner.rb、options.rb、ScreengrabfileTemplate；
• 截图客户端库（测试侧 API）：screengrab-lib 下的Screengrab、LocaleTestRule、FalconScreenshotStrategy；
• Google Play 上传：supply模块见 supply/README.md。

综上所述，screengrab/example/fastlane虽然只包含四份精简的配置文件与一份自动生成的 README，却完整覆盖了「安装 fastlane → 定义平台与 lane → 用 Screengrabfile 声明多语言 → 构建 APK → 由仪器测试逐语言截图 → 自动刷新 lane 文档」的端到端闭环，是理解 fastlane + screengrab 多语言截图工作流的最佳最小范式。

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