Lane — 定义、创建以及在Fastlane中的使用

Fastlane中的Lane是什么

Lane是Fastlane的基本构建块，定义了一个命名的自动化脚本。每个lane描述了一系列操作（actions），这些操作用于实现特定目标：构建应用程序、运行测试、将构建上传到商店或配置环境。Lane在Fastfile中声明，并通过命令fastlane [lane_name]从项目根目录运行。

Lane的概念源自Ruby DSL，确保了脚本的可读性。开发人员将整个CI/CD流程视为一系列具有清晰名称和参数的操作调用序列。Lane可以是简单的（一个命令）或复杂的（分支、循环、调用其他lane）。

每个lane在执行后返回一个结果——一个包含执行状态和操作数据的对象。结果可以在其他lane中使用，或传递给CI/CD系统用于决策。如果lane中的任何操作失败，lane的执行将停止并调用error块。

Lane语法：声明与运行

声明lane的语法遵循简单的Ruby DSL模式：关键字lane、脚本名称作为Ruby符号（symbol）、do ... end块包含脚本主体。Lane名称在同一平台内必须唯一，由字母、数字和下划线组成。

Lane通过命令行运行：fastlane build（用于名为:build的lane）或bundle exec fastlane build（如果Fastlane通过Bundler安装）。对于平台相关的lane，请使用fastlane ios build或fastlane android build。

# 声明简单的lane
lane :test do
  scan(scheme: 'App', devices: ['iPhone 15'])
end

lane :build_and_deploy do
  cocoapods
  test
  gym(scheme: 'App', export_method: 'app-store')
  pilot(skip_waiting_for_build_processing: true)
end

# 运行：fastlane build_and_deploy

Lane可以包含基于参数或环境变量的条件逻辑。使用if/unless在特定条件下跳过步骤。还可以使用each循环处理数组，这对于在一个lane中构建多个应用目标或方案非常方便。

从lane返回值

Lane可以返回一个值，该值将可供调用代码使用。返回值使用常规的Ruby return或lane块中的最后一个表达式。返回值可以是字符串、数字、哈希或操作的结果。这允许将一个lane的结果用于另一个lane中的决策。

例如，lane :get_version可以从Info.plist返回应用程序的当前版本，而lane :deploy可以使用它来生成Slack消息。返回值在private lanes中尤其有用，其中的结果需要用于调用lane中的进一步处理。

Lanes参数：传递与处理

Lane参数使脚本灵活且可复用。Lane通过options哈希接受参数，该参数在从命令行运行时传递：fastlane deploy scheme:AppStore version:2.1.0。在lane内部，参数以options[:scheme]和options[:version]的形式访问。

对于必需参数，请在lane开头检查值是否存在，并使用清晰的错误信息调用UI.user_error!。对于可选参数，使用||运算符设置默认值。Fastlane还通过options方法支持类型化参数，可以指定类型、默认值和说明。

# 带参数处理的Lane
lane :deploy do |options|
  scheme = options[:scheme]
  version = options[:version] || '1.0.0'
  beta = options[:beta] || false

  UI.user_error!("未指定scheme") unless scheme

  match(type: beta ? 'adhoc' : 'appstore')
  gym(scheme: scheme, export_method: beta ? 'ad-hoc' : 'app-store')

  if beta
    pilot(distribute_external: true)
  else
    deliver(submit_for_review: true)
  end
end

# 运行：fastlane deploy scheme:MyApp beta:true version:2.1.0

要在lane内使用环境变量，请使用ENV['VARIABLE_NAME']。Fastlane会自动从fastlane目录加载.env文件。这是在CI/CD环境中传递敏感数据（API密钥、密码和令牌）而不将其存储在Fastfile中的标准方式。

参数验证

为了lane的可靠运行，必须在输入时进行参数验证。如果必需参数缺失或类型不正确，请使用UI.user_error!并附上问题描述。Fastlane提供了options方法，可以为每个参数指定类型（String、Boolean、Integer、Array）、默认值和说明——在lane运行时自动执行验证。

此外，还可以通过verify块进行检查：verify do |value| value.length > 0 end用于字符串参数。如果格式不正确，Fastlane会显示清晰的消息，说明预期格式和传递的值，这在CI/CD环境中简化了调试。

Lanes组合：before_all、after_all与错误处理

Fastlane提供了生命周期钩子，用于在每个lane前后执行代码。before_all块在每个lane之前执行（在特定平台或全局范围内）。after_all块在lane成功完成后执行。error块在lane内发生任何错误时执行。

钩子允许集中处理重复逻辑：在before_all中安装依赖项，在after_all中发送通知，在error块中清理临时文件并报告错误。这减少了代码重复，使lane更简洁。

# Lanes生命周期钩子
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  ensure_git_status_clean
end

after_all do |lane|
  slack(message: "Lane #{lane} 成功完成")
end

error do |lane, exception|
  slack(
    message: "Lane #{lane} 因错误失败：#{exception}",
    success: false
  )
end

lane :deploy do
  match(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

error块接收两个参数：lane名称（symbol）和异常对象。在块内部，可以发送Slack通知、将日志写入文件或运行替代恢复脚本。如果error块成功完成，Fastlane不会在CI/CD级别将构建视为失败。

Private lanes与复用

Private lane是通过private_lane而不是lane声明的lane，它不会显示在可用命令列表中，也不能直接从终端运行。Private lanes用于封装从多个公共lane调用的重复步骤。

Private lanes对于必须按严格顺序执行的复杂操作序列特别有用。例如，private lane :setup_signing可以从:build_dev、:build_staging和:build_production等lane以不同参数调用，但其本身作为单独命令没有意义。

# 用于复用的Private lanes
private_lane :setup_environment do |options|
  cocoapods(try_repo_update_on_error: true)
  match(type: options[:type], readonly: true)
  increment_build_number
end

lane :dev_build do
  setup_environment(type: 'development')
  gym(export_method: 'development')
end

lane :appstore_build do
  setup_environment(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

Private lanes可以调用其他private lanes，形成抽象层级结构。建议将嵌套深度限制在2-3层，以保持Fastfile的可读性。用注释记录每个private lane，说明其用途和预期参数。

iOS和Android的Lanes示例

让我们看看iOS和Android项目的实际示例。iOS lanes通常使用scan进行测试、match用于证书、gym用于构建、pilot或deliver用于交付。Android lanes使用gradle进行构建、supply用于发布、firebase_test_lab用于云端测试。

// 完整CI/CD iOS应用的Lane
lane :ci_full_ios do
  scan(scheme: 'App', code_coverage: true)
  gym(scheme: 'App', export_method: 'app-store')
  pilot(distribute_external: true)
  slack(message: 'iOS CI/CD成功完成')
end

/* 完整CI/CD Android应用的Lane */
lane :ci_full_android do
  gradle(task: 'testReleaseUnitTest')
  gradle(task: 'bundleRelease')
  supply(track: 'internal')
end

通过组合iOS和Android的lane，可以为跨平台应用程序创建统一的CI/CD流程。使用platform :ios和platform :android平台块对特定于平台的lane进行分组，并从管理执行顺序的通用orchestrator lane中调用它们。

编写Lanes的最佳实践

在编写lanes时，建议遵循一套确保脚本可读性、可维护性和可靠性的实践。第一条规则——每个lane应该只执行一个任务。如果一个lane做的事情太多，请将其拆分为多个lane和private lanes。

第二条规则——lane命名应为动词或动词短语：build、deploy、test、upload_screenshots。避免使用process或do_all等抽象名称。使用下划线分隔lane名称中的单词。

第三条规则——显式处理错误。使用UI.user_error!提供清晰的问题消息。不要依赖Fastlane的默认错误消息——为开发人员提供上下文：“未找到GoogleService-Info.plist文件——请将其添加到项目中”，而不是“File not found”。

第四条规则——在本地测试lane后再在CI/CD上运行。Fastlane通过--dry-run标志支持dry-run模式，显示将执行哪些操作而不实际运行。使用fastlane run_test在集成前对单个lane进行隔离测试。

Lane文档

记录每个lane是团队开发的重要实践。Fastlane支持从声明lane之前的desc块自动生成文档。desc文本在运行fastlane lanes和fastlane list时显示，帮助开发人员理解每个脚本的用途而无需阅读Fastfile的源代码。

对于参数文档，使用Ruby注释描述预期值。Fastlane可以通过fastlane generate_docs命令生成包含所有lane及其描述的README.md，这有助于新团队成员适应项目的CI/CD流程。