Match (Fastlane)：什么是它、证书管理以及在开发中的配置

什么是 Match (Fastlane)？

Match (Fastlane) — 是 Fastlane 生态系统的一个组件，用于集中管理 iOS 开发的 Code Signing 证书和 Provisioning Profiles。它解决了团队成员之间签名同步的问题，并自动在 CI/CD 管道中配置证书，无需开发人员参与。

如果没有 Match，每个团队成员都通过 Xcode 或 Apple Developer Portal 手动生成证书，这会导致在不同机器上构建时发生冲突。Code Signing — 是对 iOS 应用程序进行数字签名的过程，在安装到用户设备之前确认其作者身份和完整性。

根据 Apple Developer Documentation (2025)，证书配置不正确是向 App Store 提交应用程序时被拒绝的最常见原因之一。Match 自动检查证书的有效性并警告即将到期，从而降低在 Apple 验证阶段构建被拒绝的风险。

在任何有两个或更多开发人员或具有 CI/CD 管道的项目中使用 Match — 这将把新团队成员的环境设置时间从 30 分钟减少到终端中的一个命令。

Match 如何工作：加密的 Git 存储库

Match 的架构 建立在单一真实来源的概念之上，用于 iOS 团队的所有证书。与在每个开发人员的钥匙链中本地存储不同，Match 将证书统一到一个 Git 存储库中，并在保存前对每个文件进行加密。

该过程包括三个阶段。在初始化阶段，Match 通过 Apple Developer Portal API 生成所有必要的证书和配置文件。每个文件使用 AES-256 算法加密，密钥基于用户密码短语生成。加密文件保存在 Git 存储库中，并通过标准的 Git push 和 pull 操作与远程服务器同步。

证书加密架构

Match 使用 OpenSSL 和用户密码短语的组合来加密证书和配置文件。访问密钥通过环境变量 MATCH_PASSWORD 设置，不存储在存储库中，即使在 Git 服务器被入侵或公开访问存储库的情况下也能排除泄露。

在请求证书时，Match 从存储库加载加密文件，使用密码短语在本地解密，并将其安装到当前机器的钥匙链中。构建完成后，证书可以从钥匙链中删除，以遵守企业环境的安全策略 — 这可以防止在后续构建中使用过时的证书。

每个证书都保存为包含应用程序标识符、配置文件类型和创建日期的名称。这种结构允许 Match 管理证书版本，并在需要时通过标准的 Git revert 和 reset 命令恢复到以前的状态。这在意外删除或覆盖配置文件时特别有用。

Match 的设置和配置

Match 的安装与 Fastlane 一起通过 Ruby 包管理器完成：gem install fastlane。安装后，需要使用 fastlane match init 命令初始化证书存储库，该命令创建一个空的 Git 存储库并生成包含基本设置模板的 Matchfile 文件。

# 初始化 Match 存储库
fastlane match init

通过 Matchfile 配置

Matchfile 文件包含连接到证书存储库的所有参数：Git 存储库 URL、默认配置文件类型、应用程序标识符和 Apple Developer 凭据。一个由五名开发人员组成的团队的典型配置示例：

# Matchfile configuration
git_url("https://github.com/company/certificates.git")
type(:development)
app_identifier(["com.company.app", "com.company.app.extension"])
username("developer@company.com")
team_id("TEAM123456")
git_branch("main")

type 参数定义配置文件类型：:development 用于在开发人员设备上调试，:appstore 用于在 App Store 中发布，:adhoc 用于在外部设备上测试，:enterprise 用于在 App Store 之外进行企业 In-House 分发。每种类型在存储库中创建一个单独的目录，允许按目标构建场景组织配置文件。

Match 支持 Apple Developer Portal 中的多种身份验证方法：通过 Apple ID 的双因素身份验证、App-Specific Password 和 App Store Connect API 的 API 密钥。对于 CI/CD，建议使用 API 密钥 — 它们不需要交互式输入确认码，并且在开发人员设备更改时不会阻止自动构建。

配置文件的生成和同步

配置 Matchfile 后，执行 fastlane match development 或 fastlane match appstore 命令来生成和同步配置文件。Match 通过 Apple Developer Portal API 自动创建或更新证书，并将其保存在存储库中。Apple Developer Portal — 是 Apple 用于管理证书、应用程序标识符和允许的开发人员设备列表的 Web 界面。

首次运行时，Match 将要求输入加密存储库的密码短语。此短语必须保存在 CI/CD 密钥管理器中（GitHub Actions Secrets、GitLab CI Variables 或 Jenkins Credentials），并通过环境变量 MATCH_PASSWORD 传递。没有它，Match 将无法在其他机器上或 CI 环境中解密证书。

Match 用于证书管理的基本命令

Match 界面 由一组用于创建、更新、同步和删除证书和配置文件的命令组成。每个命令对应 Code Signing 生命周期中的特定操作：从生成到完全清除存储库。

用于日常工作的命令

fastlane match development 命令加载或创建 Development 证书和配置文件，用于在本地设备上调试。Provisioning Profile — 是 Apple 的数字文档，将开发人员证书与应用程序标识符和允许安装的设备列表相关联。

对于在 App Store 中发布，使用 fastlane match appstore — 它生成 Distribution 证书和 AppStore 配置文件。fastlane match adhoc 命令创建用于在外部设备上测试的配置文件，fastlane match enterprise — 用于企业 In-House 应用程序。

# 创建用于调试的 Development 配置文件
fastlane match development

# 创建用于发布的 AppStore 配置文件
fastlane match appstore

# 导入现有的手动创建的证书
fastlane match import

fastlane match import 命令允许将现有证书添加到存储库 — 在从手动管理迁移到 Match 时很有用。--readonly 参数阻止存储库中的任何更改，这对于 CI 环境至关重要，因为管道不应自动创建或删除证书和配置文件。

要完全清除存储库，使用 fastlane match nuke 命令。它从 Git 存储库、Apple Developer Portal 和本地机器中删除所有证书 — 完全重置项目的 Code Signing 状态。该命令仅适用于严重冲突或迁移到新的 Apple Developer 帐户时。

将 Match 集成到 CI/CD 管道中

Match 的 CI/CD 集成 — 是该工具的主要优势之一。在 GitHub Actions、GitLab CI、Bitrise 或 Jenkins 管道中，Match 自动加载和安装正确的证书，无需开发人员参与。这允许从提交到最终 IPA 完全自动构建和签名 iOS 应用程序。

GitHub Actions 的典型配置包括安装 Fastlane、设置 MATCH_PASSWORD 变量和使用 --readonly 标志运行 Match。GitHub Actions — 是 GitHub 的 CI/CD 平台，根据存储库中的事件自动构建、测试和发布代码。

# 在 CI 环境中安装 Fastlane
gem install fastlane --no-document

# 以只读模式运行 Match，无权修改
fastlane match development --readonly

在 CI 中运行 Match 之前，需要配置对证书存储库的访问。Fastlane 根据 Matchfile 中的 git_url 参数自动克隆存储库。对存储库的访问通过 SSH 密钥或 personal access token 配置，这些密钥被添加到 CI 系统的机密中 — 这保证了证书不会通过公共访问而受到威胁。

在 CI 提供商的机密中配置环境变量 MATCH_PASSWORD 和 FASTLANE_APPLE_API_KEY。App Store Connect API 密钥允许 Match 在 Apple Developer Portal 中进行身份验证，无需双因素身份验证，从而消除了自动构建中的交互式请求并防止管道阻塞。

使用 Match 时的典型错误

即使正确配置了 Match，也可能会出现与证书过期、配置文件冲突或环境配置不正确相关的错误。问题诊断 Match 基于分析命令日志和检查证书 Git 存储库的时效性。

最常见的错误 — «You need to provide a password for Match» — 当环境变量 MATCH_PASSWORD 未在机器上或 CI 环境中设置时发生。解决方案：将 MATCH_PASSWORD 添加到系统环境变量中，或在运行 Match 命令时通过 --keychain_password 参数传递密码。

第二个最常见的问题是在向 AdHoc 配置文件添加新设备时证书冲突。通过 fastlane match adhoc --force 命令解决，该命令考虑新设备重新创建配置文件。Apple Developer 证书有效期为一年，之后使用它们的构建将被 App Store Connect 拒绝。Match 在到期前 30 天警告过期。

当出现 «Multiple matches found for...» 错误时，存储库中存在同一证书的多个版本。使用 fastlane match nuke 命令完全清除存储库并从 Apple Developer Portal 中删除所有证书。清除后，从头开始生成 — 这保证了配置文件的连续状态，没有重复和冲突版本。