游戏引擎 / 系统课时

iOS 证书与描述文件怎么对应

iOS 证书与描述文件怎么对应

Cocos Creator 生成 iOS 工程后,能否安装到真机或上传 App Store Connect,取决于 Xcode 的签名身份、App 标识和描述文件是否匹配。本课按顺序核对开发调试、指定设备测试与正式分发所需材料。

学习目标

  • 说清证书、私钥、App ID、Bundle Identifier 和描述文件各自的职责。
  • 按开发、Ad Hoc 和 App Store Connect 三种用途选择签名材料。
  • 在 Xcode 与终端中定位描述文件错配和真机安装失败。

签名不是只选一张证书

签名证书标识开发团队的签名身份,真正执行签名需要 Mac 钥匙串中对应的私钥。只有下载的证书文件、没有配对私钥,仍可能无法签名。

Bundle Identifier 是应用在项目中的唯一标识,例如 com.example.game;Apple 开发者后台的 App ID 关联团队标识、该 Bundle ID 及启用的能力。Xcode Target 的 Bundle Identifier 必须与描述文件允许的 App ID 匹配。

**Provisioning Profile(描述文件)**则把 App ID、允许的签名证书、权限(Entitlements)及有效期关联起来;开发和 Ad Hoc 描述文件还限定设备。它不是证书的替代品,也不是“只要下载就能安装”的通行证。

iOS 证书、App ID 与描述文件的匹配结构

按安装目标选择描述文件

用途 常用签名身份 描述文件 设备要求
Xcode 真机开发 Apple Development iOS App Development 设备纳入开发配置
向指定设备发送测试包 Apple Distribution Ad Hoc UDID 在描述文件名单内
TestFlight / App Store 发布 Apple Distribution App Store Connect 无需逐台登记测试设备

**Release 编译配置不等于发布签名。**同一份 Release 构建也能使用开发签名进行内部验证;真正上传 App Store Connect 时,必须使用符合该分发方式的签名与描述文件。Ad Hoc 虽用分发证书,却不能冒充 App Store Connect 分发配置。具体用途可对照 Apple 的分发方式说明。

此外,推送、关联域名或其他能力启用后,Target 中的 Signing & Capabilities 与 App ID 能力配置也必须相容,否则即使 Bundle ID 对上,仍可能因权限不一致而失败。

在 Cocos 和 Xcode 中核对

  1. 在 Cocos Creator 3.8 的「项目 → 构建」选择 iOS,确认 Bundle Identifier。构建后打开生成的 Xcode 工程,避免只看 Cocos 构建成功提示。
  2. 在 Xcode 选择应用 Target → Signing & Capabilities,核对 Team、Bundle Identifier 与签名设置。个人开发调试优先使用 Automatically manage signing,让 Xcode 管理开发描述文件。
  3. 若采用手动签名,选择用途正确的 Provisioning Profile,并确认本机钥匙串中具有对应证书及私钥;不要混用另一个团队的材料。
  4. 真机运行时检查设备是否已登记、描述文件是否过期;归档上传时改用 App Store Connect 对应的分发方式,并检查能力声明。

读取描述文件中的真实约束

在 macOS 终端运行以下脚本。先把 <PATH> 换成描述文件实际所在目录,文件名也按实际修改;<ID> 和 <TIME> 代表因团队、证书与有效期而变化的值。

bash
#!/usr/bin/env bash
set -euo pipefail
PROFILE="<PATH>/Game.mobileprovision"
TMP="$(mktemp)"
trap 'rm -f "$TMP"' EXIT

# 解码描述文件,查询而非修改签名约束
security cms -D -i "$PROFILE" > "$TMP"
printf 'Team ID: '
/usr/libexec/PlistBuddy -c 'Print :TeamIdentifier:0' "$TMP"
printf 'App ID: '
/usr/libexec/PlistBuddy -c 'Print :Entitlements:application-identifier' "$TMP"
printf 'Allow debugger: '
/usr/libexec/PlistBuddy -c 'Print :Entitlements:get-task-allow' "$TMP"
printf 'Expires: '
/usr/libexec/PlistBuddy -c 'Print :ExpirationDate' "$TMP"

预期输出(以允许调试的开发描述文件为例,动态字段仅作占位):

text
Team ID: <ID>
App ID: <ID>.com.example.game
Allow debugger: true
Expires: <TIME>

若为分发描述文件,get-task-allow 通常为 false;这个布尔值不能单独区分 Ad Hoc 与 App Store Connect。可继续查看解码内容中的 ProvisionedDevices:开发与 Ad Hoc 类型包含已登记设备;App Store Connect 分发不采用这份设备白名单。

失败时先查哪一项

  • 出现找不到匹配描述文件:先核对 Team 和 Bundle Identifier,再核对签名身份是否被该描述文件允许。
  • 提示签名身份不可用:检查钥匙串中证书是否有效、是否存在配对私钥,不要只反复下载描述文件。
  • 能编译却装不到指定真机:检查描述文件有效期、设备 UDID 和设备侧的开发/信任要求。
  • 开启推送等能力后报权限不匹配:同步修改开发者后台 App ID 能力,再更新或重新生成描述文件。

排查时始终按 应用标识 → 签名证书与私钥 → 描述文件 → 权限 → 设备或发布渠道 的顺序核对,远比随机切换证书更快找到原因。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

iOS 证书与描述文件怎么对应

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通