Fastlane Match iOS 证书管理

Fastlane Match iOS 证书管理

Fastlane Match 的核心思想是将所有 iOS 签名证书和描述文件加密后存储在一个私有 Git 仓库中，团队成员和 CI 服务器通过 Match 同步。

---

优势	说明
团队共享	所有人共用同一套证书，避免重复生成
自动修复	证书过期或缺失时自动重新生成
版本控制	所有变更记录可追溯，支持回滚
CI 友好	无需手动导入证书，CI 环境一键同步

一、 创建私有证书仓库

在 GitHub / GitLab / Gitea 上创建一个私有仓库，用于存储加密后的证书和描述文件：

# 例如在 GitHub 上创建
# https://github.com/<owner>/ios-certificates

务必设为私有仓库，证书文件即使加密也不应公开。

二、 初始化 Match

进入项目 iOS 目录并初始化：

cd /path/to/your/flutter-project/ios
fastlane match init

执行后会提示选择存储方式，选择 Git，然后输入证书仓库 URL：

[✔] 🚀 
[09:24:22]: fastlane match supports multiple storage modes, please select the one you want to use:
1. git
2. google_cloud
3. s3
4. gitlab_secure_files
?  1 # 选git
[09:25:52]: Please create a new, private git repository to store the certificates and profiles there
[09:25:52]: URL of the Git Repo: https://github.com/<owner>/ios-certificates # 输入证书仓库 URL

三、 配置 Matchfile

初始化后会在 ios/fastlane/ 目录下生成 Matchfile，编辑如下：

git_url("https://github.com/<owner>/ios-certificates.git")

storage_mode("git")

type("development") # The default type, can be: appstore, adhoc, enterprise or development

app_identifier("tools.fastlane.app") # 替换为你的 Bundle ID
username("user@fastlane.tools") # Your Apple Developer Portal username

如果项目有多个 App（如主应用、扩展、Watch 等），在 app_identifier 数组中添加：

app_identifier(["tools.fastlane.app", "tools.fastlane.app2"])

四、 生成证书和描述文件

首次使用 Match 需要生成证书并上传到仓库：

# 生成 App Store 发布证书
fastlane match appstore

# 生成开发证书（可选）
fastlane match development

# 生成 Ad-hoc 证书（可选，用于内部测试分发）
fastlane match adhoc

执行过程：

1. 首次会要求输入 加密密码（用于加密仓库中的证书文件），务必妥善保管
2. Match 会自动登录 Apple Developer 后台，创建证书和描述文件
3. 证书和描述文件加密后推送到 Git 仓库
4. 本地自动安装到钥匙串

提示： 如果已有证书，Match 会检测并复用；如果证书过期或缺失，会自动重新生成。

3.5 配置 Appfile

在 ios/fastlane/Appfile 中配置 App 基本信息：

app_identifier("com.yourcompany.yourapp")
apple_id("your_apple_id@example.com")
team_id("YOUR_TEAM_ID")  # Apple Developer Team ID
itc_team_id("YOUR_ITC_TEAM_ID")  # iTunes Connect Team ID（如果与 team_id 不同）

Team ID 可在 Apple Developer 后台查看。

3.6 生成 App Store Connect API Key（推荐）

相比 Apple ID + 密码，API Key 更安全且支持自动化：

1. 登录 App Store Connect
2. 进入 Users and Access > Keys
3. 点击 Generate API Key
4. 设置角色为 App Manager（最小权限原则）
5. 下载 .p8 文件，记录 Key ID 和 Issuer ID

将 .p8 文件转为 Base64 编码（避免文件传输问题）：

cat AuthKey_XXXXX.p8 | base64