fastlane cert 深度解析：iOS 代码签名证书的自动创建、查找与吊销

fastlane cert 深度解析iOS 代码签名证书的自动创建、查找与吊销【免费下载链接】fastlane The easiest way to automate building and releasing your iOS and Android apps项目地址: https://gitcode.com/GitHub_Trending/fa/fastlane本文围绕 fastlane 中get_certificates别名certaction 的官方文档展开讲清这个 action 的完整行为流程、全部命令行参数与子命令、与sigh的联动机制以及证书在本机 Keychain 中的验证原理。读完后你可以独立完成证书自动化配置并能从源码层面理解「何时新建证书、何时复用现有证书、何时抛出异常」的判定逻辑。一、cert 是什么定位与适用边界cert是 fastlane 工具链中负责iOS 代码签名证书code signing certificate管理的工具它属于 fastlane 的code_signing分类见 get_certificates.rb 中self.category返回:code_signing且仅在:ios平台生效is_supported?判断platform :ios。官方文档中有一个必须重视的提示推荐使用 match 来生成和维护证书cert只在你需要完全掌控每一步、并且熟悉代码签名细节时才建议直接使用。这是因为cert的操作粒度更细它把「查找、创建、导入 Keychain」的每个环节都暴露给了使用者适合需要自定义证书策略的 CI 场景。二、基本用法与行为语义最简命令是fastlane cert执行后它会检查本地机器上是否已安装可用的签名证书。只有当确实需要创建新证书时cert才会依次执行以下四步见 runner.rb 的create_certificate方法创建一个新的私钥private key创建一个新的证书签名请求CSRcertificate signing request生成、下载并安装证书把生成的所有文件导入本地 Keychain。三条关键行为语义cert 永远不会吊销你现有的证书。当你无法再创建更多证书时cert会抛出异常——此时你必须手动吊销一个已有证书来腾出名额。这一点在源码中得到印证create_certificate捕获创建失败后若错误信息包含You already have a current会明确报出「已达到该类型证书数量上限」见 runner.rb若包含You are not allowed to perform this operation.且创建的是 Distribution 证书则提示「只有 Team Admin 才能创建 Distribution 证书」。Apple ID 可以通过-u传入fastlane cert -u certexample.com可以用fastlane action cert查看全部可用命令与环境变量。该命令由 fastlane 的命令文档系统生成其参数列表直接来自Cert::Options.available_options见 get_certificates.rb 中available_options的实现。还有一条文档中的硬性限制cert无法从 Apple Developer Portal 下载已有证书加私钥——因为私钥永远不会离开你的电脑。所以cert的复用逻辑是「本地已安装 / 本地有私钥缓存」两种情况下文详述而不是去门户下载私钥。三、运行流程源码解析launch → run → find / createcert的完整执行链是action 层调用Cert::Runner.new.launch见 get_certificates.rbRunner 内部流程如下见 runner.rblaunch阶段先执行run主流程然后在 macOS 上用FastlaneCore::CertChecker.installed?验证新证书是否已正确装入 Keychain若非 macOS例如 Linux CI则跳过验证并打印提示。run阶段的决策逻辑确保输出目录存在FileUtils.mkdir_p(Cert.config[:output_path])并打印本次运行的配置摘要表login登录 App Store Connect若提供了api_key/api_key_pathApp Store Connect API Key走 token 认证用户名变为可选否则回退到 Apple ID 登录此时会强制要求提供usernameCert.config.fetch(:username, force_ask: true)判定是否需要新建证书若force: true直接新建否则调用find_existing_cert查找只有查不到才新建create_certificate成功即返回失败则报UI.user_error!。find_existing_cert的三级判定见 runner.rb是理解「cert 何时不新建证书」的关键顺序条件行为1证书内容存在且CertChecker.installed?判定该证书已装入本机 Keychain记录环境变量直接复用提示 Found the certificate … which is installed on the local machine2本机未安装但输出目录里存在同名{certificate.id}.p12私钥缓存通过FastlaneCore::KeychainImporter把私钥和证书重新导入 Keychain 后复用提示 Found the cached certificate …3两者都不满足记录错误、删除无用的裸证书文件最终提示 Couldnt find an existing certificate… creating a new one进入新建流程这个设计解释了文档那句话cert先检查本地是否有可用签名证书只有必要时才走「建私钥 → 建 CSR → 下载安装 → 导入 Keychain」的完整链路。四、全部参数与环境变量Options 全表运行fastlane action cert可列出所有参数其定义集中在 cert/lib/cert/options.rb。以下按源码逐项整理参数短选项环境变量类型 / 默认值说明development-CERT_DEVELOPMENTBoolean默认false创建 Development 证书而非 Distribution 证书type-CERT_TYPE字符串可选指定具体证书类型优先于development。取值mac_installer_distribution、developer_id_installer、developer_id_application、developer_id_kextforce-CERT_FORCEBoolean默认false即使已有证书也强制新建generate_apple_certs-CERT_GENERATE_APPLE_CERTSBoolean默认「macOS 且 Xcode ≥ 11」时自动为true创建 Xcode 11 及以后使用的 Apple Development / Apple Distribution 证书类型api_key_path-CERT_API_KEY_PATH兼容DELIVER_API_KEY_PATH、APP_STORE_CONNECT_API_KEY_PATH路径可选App Store Connect API Key 的 JSON 文件路径与api_key互斥api_key-CERT_API_KEY兼容DELIVER_API_KEY、APP_STORE_CONNECT_API_KEYHash敏感字段以 hash 形式传入 API Key与api_key_path互斥username-uCERT_USERNAME字符串可选Apple ID。默认值会动态取 Appfile 中的apple_dev_portal_id或apple_idteam_id-bCERT_TEAM_ID字符串可选属于多个团队时指定团队 ID默认取自 Appfile 的team_idteam_name-lCERT_TEAM_NAME字符串可选同上按团队名指定默认取自 Appfile 的team_namefilename-qCERT_FILE_NAME字符串可选证书落盘文件名的自定义不带扩展名时会自动补.ceroutput_path-oCERT_OUTPUT_PATH路径默认.证书与私钥统一存放的目录keychain_path-kCERT_KEYCHAIN_PATH路径可选自定义 Keychain 路径。macOS 上默认为~/Library/Keychains/login.keychain(-db)非 macOS 平台传入会直接报错Keychain 不支持keychain_password-pCERT_KEYCHAIN_PASSWORD敏感字段可选首次在新 Mac 上访问证书时可能需要的密码login 默认 Keychain 即 macOS 账户密码非 macOS 平台传入会报错skip_set_partition_list-PCERT_SKIP_SET_PARTITION_LISTBoolean默认false跳过设置 partition list有时很耗时。通常应保留该步骤否则 Xcode 可能反复弹窗要求允许证书用于签名platform-CERT_PLATFORM字符串默认ios证书平台ios、macos、tvos几个值得注意的默认值行为均可在 options.rb 中核对generate_apple_certs是动态默认值只要你在 macOS 上用 Xcode 11 运行cert 就会默认创建 Apple Distribution / Apple Development 类型。测试代码 runner_spec.rb 正好覆盖了这一分叉Xcode 10 用Spaceship.certificate.productionXcode 11 用apple_distribution。证书类型如何由参数推导见 runner.rb 的certificate_typestype参数最高优先级否则看generate_apple_certsEnterprise/in-house 团队不使用 Apple Distribution会回落到 iOS Distributiondevelopment: true时用 Development 类型最后按platform选择 iOS / macOS 的 Distribution 或 Development 类型。一个已知限制源码中明确 raise截至源码注释的时间点App Store Connect API 不允许通过 API Key 访问DEVELOPER_ID_INSTALLER类型该类型只能走 Apple ID 登录路径。五、CLI 子命令create 与 revoke_expired除了作为 action 在 Fastfile 中使用cert还有独立的 CLI见 commands_generator.rbfastlane cert create # 默认子命令等价于 fastlane cert fastlane cert revoke_expired # 吊销已过期的证书revoke_expired对应Cert::Runner#revoke_expired_certs!见 runner.rb它登录 App Store Connect 后用certificates.reject(:valid?)筛出过期证书逐个调用delete!。实现上有两个健壮性细节单张证书吊销失败不会中断会UI.error后继续吊销其余证书结束时汇总吊销数量。runner_spec.rb 中有两条测试专门验证「正确挑选过期证书」和「一张失败不影响其余吊销」。这条子命令恰好补上了文档中「cert 从不吊销你现有证书」留下的运维缺口它只吊销过期的绝不主动吊销仍有效的证书。六、共享值与 sigh 联动在 Fastfile 中cert执行完成后会向lane_context写入两个共享值见 get_certificates.rb共享值含义CERT_FILE_PATH证书文件路径CERT_CERTIFICATE_ID证书 ID同时它会把证书 ID 写入环境变量ENV[SIGH_CERTIFICATE_ID]注释写明「for further use in the sigh action」。而 sigh 的选项定义 中SIGH_CERTIFICATE_ID正是一个可用的环境变量名——这就是两条命令之间的隐式握手cert刚安装的证书 ID 会被紧随其后的sigh直接采用。文档推荐的经典组合是把两者放进同一个 lanelane :beta do cert sigh(force: true) end其中force: true让sigh每次运行都重新生成描述文件provisioning profile从而保证始终使用当前本机已安装的、正确的签名证书。文档中的组合示例cert sigh表达的就是同样的语义先确保证书存在再确保描述文件与证书匹配。七、Keychain 验证与 WWDR 中间证书「cert 检查本地证书是否安装」这一步由 fastlane_core/lib/fastlane_core/cert_checker.rb 实现其中有几个对排障很重要的事实CertChecker.installed?(path, in_keychain:)的计算方式是取证书文件的SHA-1 指纹sha1_fingerprint与security find-identity -v -p codesigning列出的本机有效身份比对见 cert_checker.rb。若机器上「0 valid identities found」它会打印诊断建议手动执行security find-identity -v -p codesigning并提示检查是否存在过期的 WWDR 中间证书这一经典问题。更关键的是install_missing_wwdr_certificates每次列取身份前cert 相关流程会检查 Keychain 中是否安装齐了 Apple 的 WWDR 中间证书G2–G6 等见 cert_checker.rb 中的WWDRCA_CERTIFICATES清单缺哪个就从 Apple 证书权威站点下载哪个并security import进去。WWDR 中间证书过期是「证书明明在、签名却报信任链错误」的高频根因fastlane 在这里做了自动修复。八、密码如何存储cert登录 App Store Connect 使用的凭据由 fastlane 的CredentialsManager统一管理见 credentials_manager/README.md默认情况下Apple ID 密码存储在macOS Keychain中只保存在你的本机从不离开你的电脑也可以用环境变量FASTLANE_USER/FASTLANE_PASSWORD传入凭据设置FASTLANE_DONT_STORE_PASSWORD为1可禁止密码写入 Keychain也可以走 App Store Connect API Keyapi_key/api_key_path完全绕过 Apple ID 密码——这在 CI 中是推荐做法。九、实用 Tips查看本机证书身份security find-identity -v -p codesigning这是排查「证书装了但 fastlane/Xcode 找不到」问题的第一步。多团队协作在多个开发团队之间切换时用-b team_id或在 Appfile 中配置team_id避免登录歧义。CI 中的 Keychain 参数keychain_path/keychain_password/skip_set_partition_list三个参数只在 macOS 上有效在 Linux 容器里传入会直接校验失败CI 配置中注意区分平台。非 macOS 平台的限制launch会跳过 Keychain 验证与导入打印 Skipping importing certificates as it would not work on this operating system.也就是说证书的 Keychain 安装步骤本质上依赖 macOS 环境Linux 上只能完成「生成 下载」部分。进阶查看描述文件文档提到可以安装 ProvisionQL 这类 Finder 扩展来以 Quick Look 方式直观查看mobileprovision文件内容方便核对描述文件绑定的证书是否与cert产出的一致。十、小结cert的行为可以归纳为一张决策表有 API Key 或 Apple ID 可登录 → 列出该类型全部证书 → 已在本机 Keychain 中则复用 → 有本地 p12 缓存则重导入复用 → 否则新建CSR 下载 Keychain 导入→ macOS 上再做 SHA-1 指纹验证force: true则跳过查找直接新建。它从不主动吊销有效证书数量上限到达时报错而清理过期名额的活儿交给fastlane cert revoke_expired。配合lane_context共享值与SIGH_CERTIFICATE_ID环境变量cert与sigh串联起来就构成了 fastlane 中「证书 → 描述文件」的自动化基石。【免费下载链接】fastlane The easiest way to automate building and releasing your iOS and Android apps项目地址: https://gitcode.com/GitHub_Trending/fa/fastlane创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考