Provisioning Profile：是什么、有哪些类型以及如何工作

什么是Provisioning Profile

Provisioning Profile是一种数字配置文件，格式为.mobileprovision（适用于iOS）或.provisionprofile（适用于macOS），Apple用它来控制应用程序在设备上的安装和启动。配置文件包含代码签名的元数据，没有这些元数据，应用程序无法在实体iPhone、iPad或Apple Watch上启动——模拟器不需要配置文件，因为代码不需要签名即可在真实处理器上运行。

配置文件通过Apple Developer Portal签发，并有有效期——Development和Distribution配置文件通常为一年。根据Apple的政策，配置文件会自动与签署它的Apple Developer Program证书相关联：如果证书被吊销或过期，配置文件将停止工作。

每个配置文件包含唯一的UUID，Xcode用它来在钥匙串中标识配置文件。Xcode在构建时会自动选择合适的配置文件，但开发者可以在Signing & Capabilities设置中更改选择。一台设备上可以安装无限数量的配置文件——Apple的设备管理系统（MDM）利用这一点进行企业应用程序分发。

为什么需要Provisioning Profile

代码签名是配置文件存在的主要原因。Apple要求每个在iOS设备上运行的应用程序都必须使用Apple签发的证书进行签名。Provisioning Profile起到连接作用：它确认开发者有权在此设备上运行应用程序。根据Apple Security Guide (2025)，配置文件机制即使在开发者证书被入侵的情况下也能防止恶意软件安装到用户设备上。

配置文件还确定应用程序可以使用哪些系统服务。如果应用程序使用推送通知，Apple Push Notification service (APNs)要求在配置文件中具有正确的entitlements。否则，服务器通知将无法送达设备。iCloud、App Groups、Wallet、HealthKit和其他Apple框架也适用类似规则。

与证书的区别

开发者经常混淆Provisioning Profile和Apple Certificate。证书是确认身份的数字文档（谁在签名），而配置文件是一种配置（哪个应用程序、在哪些设备上、具有哪些权限）。一个证书可以在多个配置文件中使用，而一个配置文件只关联一个证书。Apple建议为每个应用程序和每个场景创建单独的配置文件——Development、Ad Hoc、App Store。

Provisioning Profile如何工作

应用程序签名过程由依次执行的多个步骤组成。Xcode获取应用程序的二进制文件（App Bundle），使用开发者的私钥进行签名，将Provisioning Profile嵌入其中并发送到设备。设备使用Apple的公钥验证签名，将配置文件的UUID与系统中受信任配置文件的列表进行比对，只有所有检查都成功时才启动应用程序。

当用户从App Store下载应用程序时，机制有所不同。App Store Connect使用Apple自己的Distribution证书重新签署应用程序，将开发者配置文件替换为Store配置文件。这意味着通过App Store发布的应用程序在技术上是Apple签名的，而不是开发者——尽管开发者的原始签名在构建上传到App Store Connect的阶段会进行验证。

对于Ad Hoc分发，配置文件会注册允许启动的特定设备UDID。免费的Apple Developer Program账户每年限制100台测试设备。Enterprise配置文件（用于组织内部分发）不受设备数量限制，但需要有效的Apple Developer Enterprise Program订阅，费用为每年299美元。

配置文件的生命周期

Provisioning Profile的有效期自创建之日起为一年。在到期前30天，Apple开始通过Xcode和Developer Portal向开发者发送推送通知。如果配置文件过期，设备上的应用程序会继续运行（如果已经安装），但使用该配置文件的新构建将无法安装。Xcode在尝试使用过期配置文件构建时会返回代码-402620394的代码签名错误。Apple建议通过Xcode Accounts Preferences设置配置文件自动续期——这样Xcode会在到期前24小时更新配置文件。

Provisioning Profile的类型

Apple提供四种主要的Provisioning Profile类型，每种都针对应用程序生命周期的特定阶段。Development配置文件允许在添加到Apple Developer Portal的物理设备上启动应用程序，用于开发和QA测试阶段。创建Development配置文件只需要免费的Apple开发者账户。

Ad Hoc配置文件用于在有限的测试人员范围内分发应用程序，而无需使用App Store。配置文件根据UDID注册最多100台设备，应用程序可以通过iTunes、Apple Configurator或MDM解决方案直接安装。Ad Hoc构建的有效期为12个月，不需要通过Apple审核。

App Store配置文件仅用于在App Store发布应用程序，不包含设备列表——Apple在构建批准后自行管理分发。将归档上传到App Store Connect时，如果系统安装了App Store配置文件，Xcode会自动使用它。Enterprise配置文件面向拥有Apple Developer Enterprise Program的组织，允许在公司内部分发应用程序，不受设备数量限制，也无需Apple审核。

Provisioning Profile的结构

Provisioning Profile是Apple签名的DER格式文件，其内容可以通过命令行查看。macOS的Security框架可以将.mobileprovision解码为可读的XML plist。配置文件内部包含：配置文件的UUID、App ID（团队前缀 + Bundle Identifier）、证书列表、允许的设备列表（仅适用于Development和Ad Hoc）、entitlements和有效期。

App ID——应用程序的唯一标识符，由Team ID（10个字符，由Apple分配）和Bundle Identifier（例如com.example.myapp）组成。App ID可以是explicit（与Bundle Identifier精确匹配）或wildcard（用于多个应用程序的*.example.com模板）。Apple不建议将wildcard用于使用推送通知或iCloud的应用程序——这些服务需要明确的App ID。

Entitlements——配置文件内的XML块，用于确定应用程序对系统资源的访问权限。典型的entitlements包括：aps-environment（推送通知）、com.apple.developer.icloud-services（iCloud）、com.apple.security.application-groups（用于Widget和Share Extension的App Groups）。Apple根据Xcode中启用的Capabilities自动向配置文件添加entitlements。配置文件中的entitlements与代码中要求的entitlements之间任何不匹配都会导致签名错误。

在Apple Developer中创建Provisioning Profile

创建配置文件有两种方式：通过Apple Developer Portal的Web界面或通过Xcode自动创建。对于典型项目，当启用Automatically manage signing选项时，Xcode会自动管理配置文件。Xcode会在几秒钟内创建证书、配置文件和App ID，并与Apple Developer Portal同步。但是，对于CI/CD管道需要手动管理。

要在Apple Developer Portal中手动创建配置文件，需要：进入Certificates, Identifiers & Profiles部分，选择Profiles并点击"+"。然后选择配置文件类型（Development、Ad Hoc、App Store或Enterprise），从已注册列表中选择App ID，选择开发者证书，并（对于Development和Ad Hoc）选择设备。创建后，配置文件以.mobileprovision格式下载，并在Xcode中双击安装。

CI/CD服务器需要特殊方法：配置文件和证书必须存储在安全仓库中（例如GitHub Actions的secrets中）。构建时将配置文件加载到代理上，放入~/Library/MobileDevice/Provisioning Profiles文件夹，证书导入钥匙串。Fastlane——流行的签名自动化工具——提供match命令，通过加密的git仓库在开发者之间同步配置文件和证书。

示例：通过命令行检查配置文件

要诊断代码签名问题，可以解码.mobileprovision并检查其内容。下面的命令从配置文件提取XML plist并保存为可读格式：

# 将.mobileprovision解码为XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# 检查配置文件的有效期
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

Security工具来自macOS Command Line Tools，用于解码配置文件的CMS签名文件。-D标志表示解码，-i表示输入文件。解码后，plist工具将二进制plist转换为XML，grep提取到期日期。这种方法在CI/CD中很有用，用于在构建发布版本之前检查配置文件是否过期。

Provisioning Profile的常见错误

最常见的错误是在Xcode构建时出现"No matching provisioning profiles found"。当Xcode无法找到与构建配置匹配的配置文件时会出现此错误：Bundle Identifier与配置文件中的App ID不匹配、证书未安装到钥匙串或配置文件已过期。解决方法——检查target中的Signing & Capabilities设置，必要时切换到Automatically manage signing。

当尝试在UDID未添加到配置文件的设备上运行Development或Ad Hoc构建时，会出现"Provisioning profile doesn't include the selected device"错误。Apple Developer Portal允许将设备添加到现有配置文件——之后需要重新下载并安装配置文件。Xcode在自动管理签名时会自动将连接的设备添加到配置文件中。

entitlements问题在上传到App Store Connect时表现为"The executable was signed with invalid entitlements"错误。原因是配置文件中的entitlements与项目的.entitlements文件不匹配。Apple要求配置文件中的权限集是应用程序请求权限的超集。解决方法——检查Xcode target中的Capabilities，并确保所有启用的服务在配置文件中都有相应的entitlements。Fastlane包含produce命令，可将App ID和配置文件与最新的entitlements同步。