fastlane 的安装和使用

什么是 Fastlane

    Fastlane 是一整套的客户端 CI 工具集合，替代开发者处理构建和发布 App 中繁琐的任务，可以非常快速简单的搭建一个自动化发布服务，并且支持Android，iOS，MacOS。Fastlane本身没有一套特殊语法，使用的 Ruby 语言。

Fastlane 的能力

• 为 Appstore 自动生成截图
• 轻松地将测试版分发给测试人员
• 快速地将新版本发布到应用商店
• 对 App 进行代码签名，管理 App的证书、设备和描述文件
• 为代码生成文档

Fastlane 的安装

    fastlane可以通过多种方式安装。首选方法是使用Bundler。fastlane 也可以直接通过 Homebrew 安装（如果在 macOS 上）。

可以使用 macOS 的系统 Ruby，但不建议这样做，因为它可能难以管理依赖关系，并且会导致冲突。

fastlane 需要设置一些环境变量才能正确运行。

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

RVM + Ruby + Bundler

    不推荐使用系统 Ruby，可以通过 RVM 的方式安装 Ruby，fastlane支持 Ruby 2.5 或更高版本。验证当前使用的是哪个 Ruby 版本：

ruby --version
ruby 2.6.8p205 (2021-07-07 revision 67951) [x86_64-darwin21]

    建议使用bundler并定义对fastlaneGemfile的依赖。这将清楚地定义要使用的fastlane版本及其依赖关系，还将加快fastlane的执行速度。

• 在项目的根目录中创建一个./Gemfile 文件，存放下面内容

  source "https://rubygems.org"
  gem "fastlane"
  

• 运行bundle update 并添加 ./Gemfile 和 ./Gemfile.lock 到版本控制

• 每次运行fastlane时，使用 bundle exec fastlane [lane]

• 在您的 CI 上，添加bundle install为第一个构建步骤

• 要更新 fastlane，只需运行bundle update fastlane

Homebrew

brew install fastlane

系统 Ruby

sudo gem install fastlane

Fastlane 的接入

1. 项目接入 Fastlane

   fastlane init
   

2. 自定义 fastlane 以生成屏幕截图，或自动分发新版本等等。

    What would you like to use fastlane for?
    # 为 App Store 生成本地化的 iOS 屏幕截图 
   1.   Automate screenshots 
   # 自动部署至 TestFlight
   2. ✈️  Automate beta distribution to TestFlight
   # 自动部署至 App Store
   3.   Automate App Store distribution
   # 手动设置项目以自动化任务
   4.   Manual setup - manually setup your project to automate your tasks
   

3. fastlane 创建了所有必需的文件

   # 存储自动化配置 编辑需要的 lanes 和 actions （https://docs.fastlane.tools/actions）
   Generated Fastfile at path `./fastlane/Fastfile`
   # App 信息
   Generated Appfile at path `./fastlane/Appfile`
   Gemfile and Gemfile.lock at path `Gemfile`
   

Fastlane Lanes

    fastlane 根据 Fastfile 文件中定义的 lane 的内容，lane 可以视为函数，在 lane 的作用域里可以调用其它私有 lane，也可以调用多个 action 完成自动化任务，一个简单的 Fastfile 示例如下：

lane :beta do |options|
  build(release: false)
  upload_to_testflight
end

lane :release do |options|
  capture_screenshots
  build(release: true)
  upload_to_app_store       # Upload the screenshots and the binary to iTunes
  slack                     # Let your team-mates know the new version is live
end
# 私有 lane
private_lane :build do |options|
  increment_build_number
  build_app
end

执行 lane

    想执行这些任务，需要在终端中执行下面命令：

fastlane [lane] key:value key2:value2

传递参数

    上面示例的参数 key 和 key2，可以通过 options 访问，例如传递 build_number

fastlane [deploy] build_number:2 
lane :deploy do |options|
  # ...
  # ...
  increment_build_number(build_number: options[:build_number])
  # ...
end

上下文

    在不同的 action 中进行通信

lane_context[SharedValues::VARIABLE_NAME_HERE]

before_each 和 after_each

# before_each在调用任何 lane 之前都会执行
before_each do |lane, options|
  # ...
end
# after_each在调用任何 lane 之后都会执行
after_each do |lane, options|
  # ...
end

before_all 和 after_all

# before_each在调用所有 lane 之前执行一次
before_all do |lane, options|
  # ...
end
# after_each在调用所用 lane 之后执行一次
after_all do |lane, options|
  # ...
end

error

# 执行失败会走 error
error do |lane, exception, options|
  #...
end

for_lane 和 for_plateform

#for_lane 当命令行上调用的名称与块指定的名称匹配时，将调用块。
locales ['en-US', 'fr-FR', 'ja-JP']
for_lane :screenshots_english_only do
  locales ['en-US']
end

#for_platform 根据调用 fastlane 的平台提供类似的控制。
for_platform :mac do
  app_identifier "com.forplatform.mac"

  for_lane :release do
    app_identifier "com.forplatform.mac.forlane.release"
  end
end

Fastlane Actions

    fastlane 的工具叫做 action ，每一个 action 都对应一个具体的任务。命令执行的底层并不是自己实现的，而是调用其他的插件或者工具执行的。比如说，fastlane 中的 gym 工具只是 xcodebuild 和 xcpretty 工具的一个封装，调用的其实还是 xcodebuild 中的打包命令，因此参数也是一样的。下面介绍几个常用的 action:

构建

Action	描述
gym、build_app	构建和签名 App
build_ios_app	和 build_app 一致，只针对 iOS
cocoapods	运行 cocoapods
xcclean	使用 xcodebuild clean 清理工程
xcodebuild、xcbuild	使用 xcodebuild 命令构建和签名App
xcarchive	使用 xcodebuild archive 命令归档
xcexport	使用 xcodebuild -exportArchive 命令导出

工程修改

Action	描述
increment_build_number	自增 build 号
set_info_plist_value	设置 info.plist 的值
update_plist	更改指定 plist 的内容

发布

Action	描述
deliver、appstore、upload_to_app_store	发布到 Appstore，需要用户认证信息参考文档-验证

证书、描述文件的管理

Action	描述
match、sync_code_signing	通过Git 同步证书和描述文件

文档

Action	描述
appledoc	生成指定文件的 appledoc 文档

step_name

fastlane 支持为每一个 action 指定 :step_name，用作该次动作的名称，避免使用多次相同动作造成的歧义。

build_ios_app(step_name: '构建 iOS App')

Fastlane 环境变量

    fastlane 还有一个 --env选项允许加载环境特定.env文件，其存储位置在 fastlane 文件夹。.env 环境变量文件的命名约定是.env.，其加载顺序是 .env、.env.default 和 .env.app1。例如，在 fastlane 文件夹中存储了.env.beta、.env.appstore 和 .env。

fastlane  --env beta 将加载 .env 和 .env.beta

Fastlane 自动化构建项目

    在如何使用命令行自动化构建项目中描述了如何通过 Xcode 命令行工具实现，其实 fastlane 流程与其相同，并且 fastlane 减少了开发者对底层的调用，从而达到只需要编写 Fastfile 就能完成自动化构建项目。

1. 配置 .env 文件，如果有多个环境或者构建需求可以选择配置环境变量，仅供参考

   .env.development

   FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT = 40
   WORKSPACE=xxx.xcworkspace 
   SCHEME=xxx
   OUTPUT_DIRECTORY=xxx
   BUILDLOG_PATH=xxx
   FIR_API_TOKEN=xxx
   

2. 配置 Fastfile文件

   platform :ios do
     
     before_all do
        ENV["FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT"] = "40"
        cocoapods{
         repo_update:true
       }
     end
   
   
     desc "Upload to fir.im"
     lane :uploadfir do |options|
       #add actions here
       match(
         type: "adhoc", 
         readonly: true
       )
       buildProject(
         export_method:"ad-hoc",
         configuration:"xxx"
       )
       fir_cli(api_token:ENV['FIR_API_TOKEN'], skip_update_icon:true) 
     end
   
     desc "Upload to appstore"
     lane :uploadappstore do |options|
       match(
         type: "appstore", 
         readonly: true
       )
       buildProject(
         export_method:"app-store",
         configuration:"xxx"
       )
       upload_to_app_store(
         skip_metadata: true,
         skip_screenshots: true
       )
     end
   
     #hidden from lanes,list,docs
     desc "Build Project"
     private_lane :buildProject do |options|
       #add actions here
       schemeName = ENV['SCHEME']
       build_ios_app(
         step_name: '构建 iOS App',
         clean:true,
         xcpretty_utf:true,
         scheme: ENV['SCHEME'],
         workspace: ENV['WORKSPACE'],
         # 指定输出文件夹
         output_directory:ENV['OUTPUT_DIRECTORY'],
         # 指定构建日子路径
         buildlog_path:ENV['BUILDLOG_PATH'],
         configuration:options[:configuration],
         export_method:options[:export_method],
         # 可以指定 ExportOptionsList
         #export_options:{
           #provisioningProfiles:{
             # ENV["APP_BUNDLEID"] => ENV["APP_PROFILE_NAME"],
           #},
           #method:ENV['EXPORT_METHOD'],
           #signingCertificate:ENV['SIGNINGCERTIFICATE'],
           #teamID:ENV['TEAMID']
         #}
       )
     end
   end
   

3. 执行

   bundle exec fastlane ios uploadfir --env development
   

Fastlane 管理证书和描述文件

    fastlane match是codesigning.guide 概念的实现。match创建所有必需的证书和配置文件，并将它们通过 openssl 加密后存储在单独的 git 存储库中。每个有权访问所选存储的团队成员都可以使用这些凭据进行代码签名。match 还会自动修复损坏和过期的凭据，这是跨团队共享签名凭据的最简单方法。

接入

1. 准备好一个 Git 仓库

2. 项目中初始化，建议使用 SSH

   fastlane match init
   

3. fastlane 会生成一个 Matchfile 在项目的./fastlane 文件夹中。示例：

   git_url("https://github.com/fastlane/certificates")
   
   app_identifier("tools.fastlane.app")
   username("[email protected]")
   

初始化

    运行 fastlane match init 后可以运行以下命令来生成新的证书和配置文件：

fastlane match appstore 或者 fastlane match development

配置文件安装在~/Library/MobileDevice/Provisioning Profiles，而证书和私钥安装在钥匙串中，并将其通过输入的密码对其进行加密后存储在 Git 库当中。

Git 存储内容

    首次运行 match 后，Git 存储库将包含 2 个目录：

• certs文件夹包含所有证书及其私钥
• profiles文件夹包含所有配置文件

此外，match 创建了一个README.md。

使用

    要在新机器上设置证书和配置文件，只需使用以下命令运行相同的命令，通过 readonly 确保它不会创建任何新证书或配置文件。

fastlane match development --readonly

导入

    通过下面命令可以将以及存在的证书或者描述文件导入并加密到匹配存储库中，可以通过skip_certificate_matching跳过验证证书

fastlane match import --skip_certificate_matching true

系统将提示需要输入证书 ( .cer)、私钥 ( .p12) 和配置文件 (.mobileprovision或.provisionprofile) 路径。