Snapshot (Fastlane) — 本质、截图生成及移动应用中的配置

什么是 Snapshot (Fastlane)？

Snapshot (Fastlane) 是 Fastlane 生态系统的一个组件，用于自动化为 App Store 创建应用截图。它在 iOS 模拟器上运行 UI 测试，在应用的指定状态下进行截图，并将它们保存到结构化的目录中，为每种语言和设备使用正确的名称。

没有 Snapshot，开发人员需要手动启动模拟器、打开每个屏幕、通过 Cmd+S 进行截图、切换语言并对所有组合重复该过程。截图自动化是 ASO 优化的关键元素，因为 App Store 要求每个新版本都有最新的图像，而手动更新 60 多张截图需要数小时的工作。

根据 App Store Connect 文档（2025），具有本地化截图的应用程序在目标国家/地区的转化率提高 25%。Snapshot 允许团队在一次运行中更新 32 种语言的视觉内容，这对于与应用程序新功能相关的营销活动尤为重要。

在任何发布到 App Store 的项目中使用 Snapshot — 它是追求发布流程自动化和改进 ASO 的团队的标准工具。

Snapshot 如何生成截图

截图生成过程在 Snapshot 中包括几个阶段：准备 UI 测试、配置 Snapfile、启动模拟器和收集结果。Snapshot 依次为指定设备和语言启动每个模拟器，执行 UI 测试并在调用 snapshot() 函数的点进行截图。

所有测试完成后，Snapshot 将截图收集到 screenshots/[Language]/ 目录中，名称符合 App Store 要求。每张截图以 PNG 格式保存，分辨率与目标设备相对应。Snapshot 还会生成 HTML 报告，用于对所有创建图像进行视觉验证。

为 Snapshot 配置 UI 测试

为了运行 Snapshot，需要在应用程序 XCTest UI 测试代码中添加 snapshot() 调用。该函数在调用时对当前屏幕状态进行截图。开发人员在每个关键操作后放置 snapshot()：打开屏幕、输入数据、在标签间导航或显示结果。

UI 测试结构示例：测试登录应用程序，调用 snapshot("01-LoginScreen") 截取登录屏幕，然后进入主屏幕并调用 snapshot("02-HomeScreen") 截取主屏幕。XCTest 是 Apple 用于 iOS 应用程序单元和 UI 测试的框架，直接集成到 Xcode 中。

// Snapshot 的 UI 测试
- (void)testScreenshots {
    XCUIApplication *app = [[XCUIApplication alloc] init];
    [app launch];
    
    snapshot(@"01-LoginScreen");
    
    [app.textFields[@"email"] tap];
    [app.textFields[@"email"] typeText:@"user@company.com"];
    [app.buttons[@"Login"] tap];
    
    snapshot(@"02-HomeScreen");
}

处理语言和设备

Snapshot 自动为 Snapfile 中指定的每种语言切换模拟器语言。应用程序以相应的本地化启动，UI 测试以该语言执行。截图本地化是 ASO 的关键因素：用户在 75% 的情况下更倾向于使用母语内容的应用程序，包括 App Store 中的截图。

对于每个设备，Snapshot 启动一个具有相应屏幕尺寸的单独模拟器。支持 App Store 要求的所有尺寸：iPhone 6.5 英寸（iPhone 15 Pro Max）、5.5 英寸（iPhone 8 Plus）、6.7 英寸（iPhone 15 Plus）和 iPad 12.9 英寸。iOS 模拟器是内置于 Xcode 中的 iOS 设备软件仿真，用于在没有物理设备的情况下测试应用程序。

# 为所有设备和语言生成截图
fastlane snapshot

# 仅为指定设备生成
fastlane snapshot --devices "iPhone 15 Pro Max,iPhone 15"

# 生成前清理截图
fastlane snapshot --reinstall_app --erase_simulator

通过 Snapfile 配置 Snapshot

Snapfile 是 Fastlane 的配置文件，用于定义截图的生成参数：设备列表、语言、等待时间和启动选项。Snapfile 存储在 fastlane 目录中，与项目一起进行版本控制，保证了所有团队成员的一致配置。

# Snapfile — 截图配置
devices([
    "iPhone 15 Pro Max",
    "iPhone 15",
    "iPad Pro (12.9-inch)"
])

languages([
    "en-US",
    "ru",
    "de-DE"
])

scheme("MyAppUITests")
output_directory("./screenshots")
clear_previous_screenshots(true)
reinstall_app(true)
erase_simulator(true)

clear_previous_screenshots 参数在开始生成前删除旧截图 — 这可以防止输出目录中积累过时的图像。reinstall_app 在每次运行前在模拟器上重新安装应用程序，保证干净的会话，不受先前测试对新生成的影响。

erase_simulator 参数在开始测试前清除模拟器内容 — 包括缓存、设置和先前会话的数据。这对于检查应用程序引导或首次启动的测试尤其重要。Snapshot 还支持 ios_version 参数指定模拟器上的 iOS 版本，以及 stop_after_first_error 参数在第一个 UI 测试错误时停止生成。

对于 SwiftUI 项目，use_simulator_for_language 参数可用，它通过模拟器设置管理语言切换，而不是更改系统区域。Snapshot 还支持 launch_arguments 用于在启动应用程序时传递额外参数 — 适用于不同后端配置或 A/B 测试的测试。

Snapshot 生成图像的命令

Snapshot 界面包括启动生成的基本命令和用于精确控制进程的高级标志。主命令 fastlane snapshot 基于 Snapfile 配置启动截图的完整生成周期。

快速生成和过滤

fastlane snapshot --devices "iPhone 15" 命令仅为指定的设备生成截图，忽略 Snapfile 中的其余设备。--languages "en-US,ru" 过滤要生成的语言。这些标志的组合有助于在单个设备和语言上快速检查截图，而无需完整的生成周期（对于 5 个设备和 10 种语言，可能需要长达 30 分钟）。

# 为单个设备快速生成
fastlane snapshot --devices "iPhone 15" --languages "en-US"

# 重新安装应用程序后生成
fastlane snapshot --reinstall_app --erase_simulator

# 生成并附带 HTML 报告
fastlane snapshot --output_directory "./build/screenshots"

--output_directory 标志更改结果保存目录。默认情况下，Snapshot 将截图保存在 fastlane/screenshots 中。为了与 Deliver 集成，指定与 Deliverfile 预期结构匹配的目录 — 这允许将截图直接传输到发布过程，而无需在文件夹之间手动复制文件。

将 Snapshot 集成到 CI/CD 流水线

CI/CD 中的 Snapshot 是在每次发布提交时自动生成截图。Snapshot 在 Deliver 阶段之前运行，以确保 App Store 中的截图与应用程序的当前版本一致，并且不包含以前版本的过时界面元素。

在 CI 中运行 Snapshot 需要安装了 iOS 模拟器的 Xcode。在 CI 环境中，Snapshot 使用预先加载到 runner 上的 Xcode 模拟器。GitHub Actions 提供了预装 Xcode 和 iOS 模拟器的映像，无需额外配置即可运行 UI 测试。

# 在 CI 环境中运行 Snapshot
fastlane snapshot --skip_open_summary \

      --output_directory "$CI_PROJECT_DIR/screenshots"

# 将截图保存为 CI 工件
cp -R "screenshots/" "$CI_PROJECT_DIR/artifacts/"

--skip_open_summary 参数禁用生成后打开 HTML 报告 — 在 CI 环境中图形界面不可用。生成结果保存在一个目录中，作为 CI 任务的工件传递，然后由 Deliver 用于与版本一起上传到 App Store。

为了加速 CI 流水线，请通过 concurrent_simulators 使用并行截图生成 — 一个 Snapfile 参数，可以同时启动多个模拟器。使用 4 个并行线程时，这将 5 个设备和 10 种语言的截图生成时间从 40 分钟缩短到 15 分钟。

使用 Snapshot 时的常见错误

在使用 Snapshot 时，开发人员最常遇到与 UI 测试不稳定、模拟器问题和设备配置错误相关的错误。错误诊断从分析 HTML 报告开始，该报告包含每个步骤的截图和有关失败测试的信息。

“Failed to build scheme MyAppUITests”错误发生在 UI 测试方案未配置构建时。解决方法：确保在 Xcode 中为 UI 测试创建了单独的 Scheme，并且为命令行访问启用了 Shared 选项。Xcode Scheme 是应用程序构建、测试和启动的配置，定义了每个操作的目标和参数集。

“No simulators found matching...”错误表示没有具有指定设备类型或 iOS 版本的模拟器。解决方法：执行 xcrun simctl create 创建模拟器，或从 xcrun simctl list 列表中指定现有设备。xcrun simctl 是 Xcode 用于管理 iOS 模拟器的命令行工具：创建、删除、启动和诊断。

在“UI test failure”错误中，UI 测试在一种语言或设备上失败。解决方法：使用 --stop_after_first_error 标志运行 Snapshot，在第一个错误处停止，分析 HTML 报告中的截图并修复测试。常见原因是不同语言的文本长度不同，导致界面元素重叠或超出屏幕边界。