iOS证书和分发配置文件解释

iOScode签名使用两部分。 A 证书 证明了应用程序的开发者身份 证书配置文件 它说哪个应用程序是哪些设备可以运行它以及它可以使用哪些功能。 Xcode拒绝为设备编译，并且App Store Connect拒绝上传，除非证书、其私钥和匹配的配置文件都齐全。

本指南解释了每个部分，开发、无线广播、TestFlight、App Store和企业版的组合，您需要哪些组合，如何在有或没有Mac的情况下创建它们，以及如何修复您将遇到的错误。

为什么苹果要求code签名

苹果只允许iPhone运行code，这些可以追溯到已知开发者的应用程序。签名给苹果提供了三个保证:

1. 身份上下文: 企业产品/定价页面。角色: 短UI标签或导航项。见于: 企业版astro页面。消息键`enterprise_plugins_legacy_identity` (企业插件遗留身份)。
2. Integrity完整性
3. Authorization授权

：应用程序允许在此设备上运行，具有这些特权（推送、iCloud、使用Apple ID登录、应用组等）。

构建块

最常见的混淆点：一个 .cer 文件本身是无用的。签名需要创建 CSR 的私钥。如果您丢失了该密钥，则需要创建新的证书。

证书类型

Apple 开发

用于在 Xcode 中从开发者自己的设备上运行构建。开发证书属于个人开发者，Apple 会将其标记为计算机名称。团队中的每个开发者都可以有自己的。

Apple 发布

用于签署用于 Ad Hoc 分发、TestFlight 和 App Store 的构建。分发证书属于团队，仅 Account Holder 或 Admin 角色可以创建它们。苹果限制团队可以持有的证书数量，因此请通过安全存储共享一个，而不是让每个开发者创建自己的证书。

您可能仍然会看到 iOS 开发 和 context: HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `compare_step_capacitor_text`）。页面/区域：Capgo 市场网站。角色：网站副本句子。见于：页面 alternatives/expo.astro，页面 alternatives/median.astro。消息键 `compare_step_capacitor_text`（Compare Step Capacitor Text）。| 页面/区域：Capgo 市场网站。角色：短 UI 标签或导航项。见于：页面 trust.astro。消息键 `and`（And）。 iOS 分发

您可能会遇到的其他证书类型

• 您可能会遇到的其他证书类型是开发者 ID 应用程序/安装程序
• :用于在 Mac App Store 之外分发 Mac 应用程序的证书。用于 iOS 的证书。Apple 推送通知服务 SSL :遗留的推送证书。建议使用一个 (.p8iOS证书和配置文件简介 APNs证书指南.
• Apple Pay商家身份, Pass Type ID, 网站推送ID:特定服务

配置文件类型

一个配置文件与 一个 App ID. 如果您的应用程序具有扩展（一个小部件、一个通知服务扩展、一个共享扩展），则每个目标都有自己的包 ID，并且需要自己的配置文件。

各个部分如何协同工作

当 Xcode 或一个构建服务签署您的 Capacitor 应用程序时，它会检查：

1. 目标中的包 ID（例如 com.example.app)与配置文件中的 App ID 匹配。
2. 用于签名的证书是配置文件中列出的证书之一。
3. 用于该证书的私钥可在钥匙串中找到。
4. 对于开发和 ad hoc 构建，设备的 UDID 在配置文件中。
5. 应用特权文件（推送，关联域名，App 组）是 App ID 和配置文件允许的子集。

如果任何检查失败，您会得到一个签名错误，而不是运行时崩溃，这很好：您在发布之前就知道了。

我需要哪种组合？

TestFlight使用的签名与App Store相同。没有单独的TestFlight配置文件。您上传一个构建，然后在App Store Connect中决定它是否发送给测试者、审查或两者。 创建证书和配置文件 选项1：让Xcode管理签名

对于本地开发来说这是最简单的。打开

选项 1：让 Xcode 管理签名

本地开发最简单。 ios/App/App.xcworkspace (或) .xcodeproj when your Capacitor 8 project uses Swift Package Manager), select the App 目标, 打开 签名 & 能力, tick 自动管理签名 并选择您的团队。 Xcode 创建开发证书，注册连接的设备并为您生成配置文件。

自动签名在 CI 中变得痛苦，因为构建机器需要访问团队帐户并在其上创建证书。 大多数团队会切换到手动签名，或者在发布构建中使用 API-密钥签名的构建服务。

选项 2：在 Mac 上手动创建它们

1. 打开 钥匙串访问 > 证书助手 > 从证书颁发机构请求证书. 输入您的电子邮件，选择 保存到磁盘iOS证书和配置文件简介。 .certSigningRequest file.
2. 在Apple Developer门户中，前往 证书、标识符和配置文件 > 证书 > +，选择 Apple Distribution（或Apple Development）并上传CSR。 下载
3. 并双击它。Keychain Access将其与私钥配对。 .cer 要导出用于CI：在Keychain Access中，右键单击证书，选择
4. My Certificates ，然后选择Export 导出, 保存为 .p12 使用强密码

选项 3：在 Mac 上创建它们

您可以使用 OpenSSL 在 Linux 或 Windows 上完成整个流程：

# 1. Private key and CSR
openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Example Inc/C=US"

# 2. Upload ios_distribution.csr in the Apple Developer portal,
#    download the certificate as distribution.cer

# 3. Convert the .cer (DER) to PEM
openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM

# 4. Build the .p12 (signing identity)
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
  -out ios_distribution.p12 -legacy

该 -legacy 标志在 OpenSSL 3 中很重要：如果没有它， .p12 使用加密算法的 OpenSSL 3 将 macOS keychain 工具拒绝使用“无效密码”错误，即使密码正确。

如果您不想安装 OpenSSL， iOS 证书生成器 会为您创建 CSR 和私钥。它们来自一个无状态的Capgo端点，不存储它们，只有 .cer 到 .p12 浏览器中运行的转换器。如果您的政策要求在您的机器上生成密钥，请使用上面的 OpenSSL 命令。

创建配置文件

1. 标识符 > +: 注册一个与您的确切包 ID 匹配的 App ID，并启用您使用的功能（推送通知、Apple 登录、关联域名等）。
2. 设备 > +: 为开发和 ad hoc 配置文件注册每个测试者的 UDID。测试者可以在手机上使用 iOS UDID 寻找器，无需 Mac 或有线连接。
3. 配置文件 > +: 选择配置文件类型、App ID、证书（证书）和设备。为其命名，例如 com.example.app AppStore 2026.
4. 下载 .mobileprovision 文件。

如果您在后期添加设备或能力，您必须重新生成并重新下载配置文件。现有的配置文件不会自动更新。

检查配置文件

A .mobileprovision 文件是签名的plist。macOS中您可以读取它：

security cms -D -i App_Store.mobileprovision > profile.plist
/usr/libexec/PlistBuddy -c "Print :Name" profile.plist
/usr/libexec/PlistBuddy -c "Print :ExpirationDate" profile.plist
/usr/libexec/PlistBuddy -c "Print :Entitlements" profile.plist
/usr/libexec/PlistBuddy -c "Print :ProvisionedDevices" profile.plist

在Linux中， openssl smime -inform der -verify -noverify -in App_Store.mobileprovision 打印plist。

要检查一个构建 .ipa 使用什么签名：

unzip -q App.ipa -d ipa
codesign -dvv ipa/Payload/App.app
codesign -d --entitlements :- ipa/Payload/App.app

有效期和续期

• 证书 有效期为一年的创建时间。
• 配置文件 一年后失效，或在证书过期或被吊销时更早失效。
• App Store 应用程序仍然可以正常运行 直到分发证书过期。 Apple 会重新签名 App Store 下载。您只需要一个新的证书才能上传新的构建。
• Ad Hoc 和开发构建停止启动 一次其配置文件过期。测试人员在启动时会看到应用程序崩溃。
• 测试Flight 构建 90 天后失效，独立于证书。
• 企业应用程序在每台设备上停止工作 当企业证书过期或被吊销时。请在过期前续期。
• 设备槽位 每年一次重置。移除设备不会释放其槽位，直到下一年开始。

将证书过期日期放入共享日历中。我们的 证书管理指南 涵盖监控和轮换的更多内容。

常见错误和解决方案

“找不到 iOS 分发签名证书” 或 “签名证书无效”:私钥未在此钥匙链中。导入 .p12，或创建新证书，如果没有人拥有密钥。

“配置文件未包含签名证书”:配置文件使用不同的证书创建。编辑配置文件，勾选当前证书，重新生成并下载。

“配置文件未包含当前选择的设备”:注册 UDID，重新生成配置文件。对于 TestFlight 或 App Store 不需要。

“不支持推送通知能力的配置文件”：在 App ID 中启用该能力，然后重新生成配置文件。配置文件是快照。

“找不到此可执行文件的有效配置文件” ：在安装时，设备不在 ad hoc 配置文件中，或者配置文件已过期。

应用程序安装后立即关闭：在 iOS 16 和更高版本中，开发和 ad hoc 构建需要在设备上启用开发者模式。请参阅 如何在 iOS 上启用开发者模式.

扩展无法签名：每个扩展目标都需要自己的 App ID 和配置文件。检查 Signing & Capabilities 中的每个目标，而不是仅 App。

导入 Linux 上生成的 .p12 时出现“无效密码”：使用 openssl pkcs12 -export ... -legacy.

拒绝上传 SDK 版本: since April 2026 App Store Connect requires builds made with Xcode 26 and the iOS 26 SDK. Update Xcode or your CI image. Capacitor 8 already requires Xcode 26.

团队的好实践

• 每个团队只有一份 Apple 分发证书，存储在一个 .p12 在密码管理器或密钥存储中，密码单独存储。
• 永远不要通过电子邮件 .p12 文件或将它们提交到 Git。
• 使用 App Store Connect API 密钥（.p8）进行上传，而不是 Apple ID 密码。
• 以包 ID、类型和年份命名配置文件。
• 撤销离开团队的人的证书。
• 保持每个包 ID、扩展和能力的书面清单。

Capacitor 应用程序的云签名

您不需要在每个开发者的桌面上安装 Mac 才能发布 iOS 版本。 Capgo 构建 构建 Capacitor 应用程序在 Capgo 的 macOS 机器上使用 .p12 并且您提供的配置文件。 仅用于构建，且不存储在Capgo服务器上。 请您只在CLI中保存它们。

bunx @capgo/cli@latest build credentials save --appId com.example.app --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --path .

The 列出了准确的凭证选项，包括 App Store Connect Capgo 密钥用于 TestFlight 上传和 list 出具体的凭证选项，包括 App Store Connect API keys 用于 TestFlight 上传和 ad_hoc 一旦您的第一个构建在 TestFlight 中，

您可以使用 Capgo 实时更新 Capgo 实时更新 不需要重新签名新的二进制文件来修复问题。原生code更改和新功能仍然需要通过商店进行签名的构建。

__CAPGO_KEEP_0__

• 需要账号吗? 如何创建苹果和谷歌Play开发者账号.
• 准备将构建分发给测试者吗? 如何分发iOS和Android应用到测试者.
• 提交？阅读我们的 iOS应用提交指南.