使用fastlane match自动化管理证书和描述文件-六虎

在咱们进行团队开发的时分，避免不了证书和描绘文件的办理，惯例的有主动办理和手动办理两种方法。

1. 惯例的办理方法

1.1 主动办理签名

需求在Xcode的 Targets->Signing & Capabilities 勾选 Automatically manage signing。用这种方法，一切的作业包括AppId、证书、描绘文件(Provisioning Profile)的创立都由Xcode包办了，十分的方便。

这种方法对个人开发者十分友爱，可是对团队开发来说有比较大的坏处，具体如下。

1.1.1 每个开发成员都有单独的证书和描绘文件，会导致存在很多重复的文件，办理起来十分混乱

如图所示：

1.1.2 证书的创立是有上限的，可能会导致其他人无法创立证书。

1.1.3 每次增加新设备或证书过期时，都必须手动更新和下载最新的装备文件集

比如说，增加新设备后，假如描绘文件装备里边没有勾选这个设备，这个设备是无法装置咱们的运用的，一切每次都需求保证描绘文件的Select All是否已勾选。

1.2 手动办理签名

首先，需求某个团队成员先在 Apple Developer 后台别离创立开发环境和生产环境的证书和装备文件，然后将这些文件下载装置到本地。当其他人参与开发时，需求这个人将相关的文件导出给其他人。

然后需求在 Xcode上吊销勾选 Automatically manage signing，同时设置对应的证书和描绘文件(Provisioning Profile)。

这种方法的优点是一切开发人员都共用一份证书和描绘文件，缺陷也十分显着：每次证书过期或许增加新的设备后，都需求手动去更新，然后从头分发其他人，操作起来十分费事。

那么，有没有这么一个方案：在一个公共的地方存取这些证书和装备文件，主动化去处理整个流程呢？这便是咱们今天要讲的 match 东西。

2. 运用 fastlane match 主动化办理证书和装备文件

match 是 fastlane 东西套装其间的一个东西，它是 codesigning.guide 概念的实现。它供给了一种全新的办理证书的方法，使团队一切成员同享一份代码签名，以减免不必要的证书创立、装备文件失效等问题。

2.1 运用 match 有什么优势？

一切的团队成员同享同一份证书和装备文件，减少了办理和保护成本
简化请求证书，生成描绘文件，注册设备等一系列冗杂作业
能主动识别已过期的证书和失效的描绘文件，对这些文件进行重置
对新开发者极端友爱，match运用git办理一切的证书和描绘文件，所以只需新人具有git的访问权限，装置了fastlane，就能快速同步现有的证书装备，远离证书装备的大坑

2.2 怎么运用 match ？

下面我将具体介绍 match 的运用流程。

2.2.1 准备一个私有的 git库房

创立一个私有git库房来存储证书和描绘文件。主张在git账号中装备好SSH Key，这样就能够省去身份校验这一步。至于怎么装备SSH Key，请参阅：运用 SSH 连接到 GitHub。

别的，当有多个App时，~~主张一个git分支对应一个App~~（这儿有问题，请参阅本文 2.2.5节多个App复用同一个证书），这样，咱们一切App的证书都在一个库房里边，便于办理。

2.2.2 初始化 match

在终端定位到项目目录，留意先看项目目录下是否存在fastlane目录，假如没有的话，先履行 fastlane init 指令来初始化fastlane服务（后面会用到）。然后再履行 fastlane match init 指令，首先会提示让你挑选存储方法，咱们选git，然后再输入git库房地址，最后会生成一个 Matchfile 的装备文件。接下来，咱们修正一下 Matchfile。

git_url("git@github.com:YourUserName/certificates.git")  # git库房地址
storage_mode("git") # 存储方法
git_branch("master")  # git分支称号
# 默许的Profile类型, 能够为: appstore, adhoc, enterprise or development
type("development") 
# bundleId，能够填多个bundleId，如App内包括 extension
app_identifier(["tools.fastlane.app", "tools.fastlane.app2"])
ENV["MATCH_PASSWORD"] = "your match password" # 导出和打开 .p12文件的暗码
# username("user@fastlane.tools") # Your Apple Developer Portal username
# For all available options run `fastlane match --help`
# Remove the # in the beginning of the line to enable the other options
# The docs are available on https://docs.fastlane.tools/actions/match

装备完 Matchfile 后，大部分教程都是让你经过以下三条指令来同步证书和装备文件。

fastlane match development
fastlane match adhoc
fastlane match appstore

可是这种方法运用起来十分不方便，特别是用于主动化构建脚本，因为每次都要输入AppleId和暗码；有的团队的做法是在Matchfile装备一个共用的AppleId，这样就不必每次输入账户和暗码。

git_url("git@github.com:YourUserName/certificates.git")  # git库房地址
# 省掉其他内容...
username("APPLE_ID") # 共用的AppleId
ENV["FASTLANE_PASSWORD"] = "AppleId暗码"

可是，还会遇到别的一个问题，需求进行双重验证，要求输入6位验证码，每次都要输入验证码，这样体验是十分不好的，并且无法用于CI/CD，所以我个人更引荐用 App Store Connect API 的方法，下面我将对这种方法做具体介绍。

2.2.3 创立 App Store Connect API 秘钥

App Store Connect API 是官方供给的一套 REST API，可让您在 App Store Connect 中履行的操作主动化。它主要供给了以下功能（包括了证书和描绘文件的办理）：

用有办理员权限的AppleID登录 AppStoreConnect 后台，挑选用户和访问->秘钥，点击增加按钮来生成API秘钥。

然后下载API秘钥（一个.p8文件），保存到项目的fastlane目录。留意：私钥只能下载一次，永远不会过期，保管好，假如丢失了，去App Store Connect后台吊销密钥，不然他人拿到也能够用。

2.2.4 创立主动化脚本

为了更加方便运用，咱们经过 fastlane 来装备几个常用的指令，将以下内容增加到你的 fastlane目录下的 Fastfile 文件中：

# 界说一个全局变量api_key，下面都会要用到这个 api_key
# key_id 和 issuer_id 都能够在 AppStoreConnect后台 -> 用户和访问 -> 秘钥 这儿找到
api_key = app_store_connect_api_key(
    key_id: "D383SF739",
    issuer_id: "6053b7fe-68a8-4acb-89be-165aa6465141",
    key_filepath: "./AuthKey_D383SF739.p8", # 上面下载的p8文件路径
    duration: 1200, # optional (maximum 1200)
    in_house: false # optional but may be required if using match/sigh
)
desc "下载一切需求的证书和描绘文件到本地，不会从头创立证书和描绘文件（只读方法）"
lane :match_all do
    match(api_key: api_key, type: "development", readonly: true)
    match(api_key: api_key, type: "adhoc", readonly: true)
    match(api_key: api_key, type: "appstore", readonly: true)
end
desc "同步证书，假如证书过期或新增了设备，会从头创立证书和描绘文件"
desc "该方法仅限办理员运用，其他开发成员只需求运用 match_all 方法即可"
  lane :force_match do
    match(api_key: api_key, type: "development", force_for_new_devices: true)
    match(api_key: api_key, type: "adhoc", force_for_new_devices: true)
    match(api_key: api_key, type: "appstore")
end
desc "注册设备，并更新描绘文件"
lane :sync_devices do
    # devices.txt模板：
    # http://devimages.apple.com/downloads/devices/Multiple-Upload-Samples.zip
    register_devices(api_key: api_key, devices_file: "./devices.txt")
    match(api_key: api_key, type: "development", force_for_new_devices: true)
    match(api_key: api_key, type: "adhoc", force_for_new_devices: true)
end
# 构建测验包
lane :beta do
  # 先同步adhoc证书和描绘文件
  match(api_key: api_key, type: "adhoc", readonly: true)
  # 省掉其他过程...
  build_app(scheme: "MyApp",
            workspace: "Example.xcworkspace",
            include_bitcode: true)
end 
lane :release do
  # 先同步appstore证书和描绘文件
  match(api_key: api_key, type: "appstore", readonly: true)
  # 省掉其他过程...
  build_app(scheme: "MyApp")
  # 上传运用到AppStore
  upload_to_app_store(
        api_key: api_key,
        force: true, # Skip HTMl report verification
        skip_screenshots: true,
        skip_metadata: true,
        submit_for_review: false,
  )
end

经过上面这个模板我界说了以下几个常用的指令：

fastlane match_all：下载一切需求的证书和描绘文件到本地，不会从头创立证书和描绘文件（只读方法）
fastlane force_match：强制同步证书和描绘文件，假如证书过期或新增了设备，会从头创立证书和描绘文件
sync_devices：注册设备，会同步更新描绘文件，需求先在 devices.txt 文件录入新增的设备UDID。
fastlane beta：构建测验包，先经过 match 保证adhoc证书和描绘文件都是最新且有效的
fastlane release：构建且上传到AppStore，先经过 match 保证 appstore证书和描绘文件都是最新且有效的。

当咱们有新搭档入职，或许需求在新的电脑上装备开发证书和描绘文件，咱们只是只需求一条 fastlane match_all 指令即可。

2.2.5 多个App复用同一个证书 — 2023/07/04 新增

在实际运用过程中，咱们发现一个问题，同一个开发者账号下，假如有多个App，每个App Matchfile 文件按如下方法装备:

# Matchfile 文件
# 省掉其他内容...
git_branch("appName") # 分支名用App称号

咱们以App称号作为分支名，每次履行 fastlane force_match，每个App都会测验去创立新的开发证书和分发证书。又因在同一个开发者账号下，所运用的API Key是相同，所以生成的证书称号都是相同的，这样会导致本地装置多份同名的证书，而描绘文件和证书称号又是一一匹配的，Xcode在匹配的过程中无法识别具体要匹配哪一个（据观察，默许是去匹配最新创立的证书），这样就导致部分App匹配失败。

既然是多份开发证书的问题，那有没有办法多个App复用同一份开发证书呢，答案当然是有的，解决方案也很简单，便是同一个开发者账号下的App都用相同的分支称号：

# Matchfile文件
git_url("https://github.com/example/example-repo.git")
git_branch("teamName")    # git分支称号，同一个开发者账号下用相同的分支称号，如Team Name

详情请参阅 fastlane match 官方文档：

3. 其他

3.1 怎么吊销一切的证书和描绘文件

很少会有这种需求，假如的确需求清空一切证书和描绘文件的话，能够经过 fastlane match_nuke 东西来处理：

desc "清空一切的证书和描绘文件，慎用"
lane :nuke_all do
    match_nuke(api_key: api_key, type: "development")
    match_nuke(api_key: api_key, type: "adhoc")
    match_nuke(api_key: api_key, type: "appstore")
end

留意：清空完一切的证书和描绘文件后，已装置的测验包是无法运用的，慎重运用。

3.2 怎么检查设备的UDID

1. 经过Xcode来检查

先经过USB在电脑上连接iOS设备，然后在Xcode中打开菜单：Window -> Device and Simulators，上面显示的 Identifier 这一项便是咱们所需求的设备UDID。

2. 经过第三方东西

假如当前无法运用Xcode来检查，如其他地区的搭档，能够运用第三方东西。大部分供给运用分发的平台都支撑获取UDID，如 Fir获取UDID、蒲公英-快速获取iOS设备的UDID。

3.3 怎么判断某个测验包是否能在设备上运行

原理：描绘文件里边包括了一切的支撑装置的设备的UDID，所以咱们只需求看描绘文件里边是否包括该设备的UDID就行了。在咱们构建IPA包时，里边会嵌入一个叫 embedded.mobileprovision 文件（其实便是描绘文件），判断咱们的设备UDID是否在包括这个文件中，就能判断是否能装置（当然这只是其间的一个条件，其他的没在本文范围内，不做过多介绍）。

可是，这个文件是无法直接打开检查的，因为它经过了特别的编码，其实质是一个plist文件，咱们能够经过以下方法来检查它：

1. 经过 security 命名解码检查

security cms -D -i embedded.mobileprovision > result.plist
open result.plist

2. 运用预览插件 ProvisionQL 检查

能够经过 brew 来装置 ProvisionQL，装置指令为： brew install --cask provisionql 。在文件扩展名为 .ipa 、 .xcarchive 或 .mobileprovision 上可经过空格键来快速预览。

4. 参阅资料

fastlane match
A new approach to code signing
App Store Connect API官方文档
fastlane – Using App Store Connect API
JWT
ProvisionQL – Quick Look for ipa & provision

使用fastlane match自动化管理证书和描述文件