一、什么是 Entitlements(授权)Entitlements是苹果生态系统(iOS/macOS/tvOS/watchOS)中的一种权限机制,用于声明应用程序需要访问的受保护的系统资源或能力。它本质上是一个XML 格式(plist)的键值对文件,在应用签名时嵌入到二进制中,由系统内核在运行时验证。?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeycom.apple.security.app-sandbox/keytrue//dict/plist二、Entitlements 的工作原理开发者在 Xcode 中启用某个 CapabilityXcode 自动生成.entitlements文件编译时通过codesign命令嵌入到应用签名中App Store 审核 / 系统内核验证是否匹配 Provisioning Profile运行时由amfid(AppleMobileFileIntegrity)守护进程强制执行三、Entitlements 分类详解 1. App Sandbox(应用沙盒)- 仅 macOSkeycom.apple.security.app-sandbox/keytrue/解释:启用后,应用被限制在一个隔离的容器中,只能访问被明确授权的资源。Mac App Store 应用必须启用。 2. 网络权限keycom.apple.security.network.client/keytrue/keycom.apple.security.network.server/keytrue/network.client:允许应用发起对外的网络连接(如 HTTP 请求)network.server:允许应用监听端口,接受外部连接(如作为服务器) 3. 文件访问权限keycom.apple.security.files.user-selected.read-only/keytrue/keycom.apple.security.files.user-selected.read-write/keytrue/keycom.apple.security.files.downloads.read-write/keytrue/user-selected.read-only:用户通过打开面板选择的文件,只读user-selected.read-write:同上,可读写files.downloads.read-write:直接访问 Downloads 文件夹 4. 硬件设备权限keycom.apple.security.device.camera/keytrue/keycom.apple.security.device.microphone/keytrue/keycom.apple.security.device.usb/keytrue/keycom.apple.security.device.bluetooth/keytrue/camera:访问摄像头microphone:访问麦克风usb:访问 USB 设备bluetooth:访问蓝牙⚠️ 注意:除了 entitlement 之外,还需要在Info.plist中添加Usage Description(如NSCameraUsageDescription)。 5. 个人信息访问权限keycom.apple.security.personal-information.location/keytrue/keycom.apple.security.personal-information.addressbook/keytrue/keycom.apple.security.personal-information.calendars/keytrue/keycom.apple.security.personal-information.photos-library/keytrue/location:定位addressbook:通讯录calendars:日历photos-library:相册☁️ 6. iCloud 相关keycom.apple.developer.icloud-container-identifiers/keyarraystringiCloud.com.example.app/string/arraykeycom.apple.developer.icloud-services/keyarraystringCloudKit/stringstringCloudDocuments/string/arraykeycom.apple.developer.ubiquity-kvstore-identifier/keystring$(TeamIdentifierPrefix)$(CFBundleIdentifier)/stringicloud-container-identifiers:iCloud 容器 IDicloud-services:启用的 iCloud 服务(CloudKit / iCloud Drive)ubiquity-kvstore-identifier:iCloud 键值存储(NSUbiquitousKeyValueStore) 7. 推送通知keyaps-environment/keystringdevelopment/string!-- 或 production --解释:启用 APNs 推送。development用于开发调试,production用于 App Store 发布。 8. In-App Purchase / 支付keycom.apple.developer.in-app-payments/keyarraystringmerchant.com.example.app/string/array解释:Apple Pay 商户 ID,用于支付。 9. Keychain 共享keykeychain-access-groups/keyarraystring$(AppIdentifierPrefix)com.example.shared/string/array解释:允许多个应用共享钥匙串数据,常用于同一开发者的多个 App 之间共享登录凭据。 10. App Groups(应用组)keycom.apple.security.application-groups/keyarraystringgroup.com.example.shared/string/array解释:让**主 App 与扩展(Extension、Widget)**之间共享数据(通过 UserDefaults、文件系统)。 11. Associated Domains(关联域名)keycom.apple.developer.associated-domains/keyarraystringapplinks:example.com/stringstringwebcredentials:example.com/stringstringactivitycontinuation:example.com/string/arrayapplinks:通用链接(Universal Links)webcredentials:网站密码自动填充activitycontinuation:Handoff 接力 12. CarPlaykeycom.apple.developer.carplay-audio/keytrue/keycom.apple.developer.carplay-communication/keytrue/解释:各种 CarPlay 应用类型的授权(音频、通讯、导航等),需向苹果单独申请。 13. HealthKit / HomeKitkeycom.apple.developer.healthkit/keytrue/keycom.apple.developer.homekit/keytrue/解释:健康数据 / 家居设备控制。 14. Network Extensions(网络扩展)keycom.apple.developer.networking.networkextension/keyarraystringpacket-tunnel-provider/stringstringapp-proxy-provider/stringstringcontent-filter-provider/string/array解释:开发 VPN、防火墙、内容过滤应用时需要,必须向苹果单独申请。 15. Game Centerkeycom.apple.developer.game-center/keytrue/ 16. SiriKitkeycom.apple.developer.siri/keytrue/ 17. Sign in with Applekeycom.apple.developer.applesignin/keyarraystringDefault/string/array️ 18. Print(打印,macOS 沙盒)keycom.apple.security.print/keytrue/⚙️ 19. 特殊/系统级 Entitlementskeycom.apple.security.cs.allow-jit/keytrue/keycom.apple.security.cs.allow-unsigned-executable-memory/keytrue/keycom.apple.security.cs.disable-library-validation/keytrue/keycom.apple.security.cs.debugger/keytrue/allow-jit:允许 JIT 编译(如 JavaScriptCore、模拟器)allow-unsigned-executable-memory:允许未签名的可执行内存disable-library-validation:允许加载非同签名的动态库(插件系统)cs.debugger:允许作为调试器附加到其他进程四、Entitlements 文件的实际操作1. 在 Xcode 中启用Target → Signing Capabilities → Capability2. 查看已签名应用的 Entitlementscodesign-d--entitlements:- /path/to/App.app3. 手动签名时指定codesign--entitlementsMyApp.entitlements--signDeveloper IDMyApp.app五、Entitlements 的三个关键约束层级说明Provisioning Profile描述文件必须包含对应的 entitlement,否则无法安装App ID Capabilities苹果开发者后台的 App ID 必须开启对应能力代码签名签名时嵌入 entitlements,不能后期修改三者必须一致,否则会出现:Provisioning profile doesnt include entitlementMissing entitlementsCode signing error六、常见问题排查Entitlement 不生效:检查 Provisioning Profile 是否包含签名失败:检查 App ID 是否已启用该能力上架被拒:检查 entitlement 是否需要苹果特批(如 CarPlay、NetworkExtension)企业签 / 重签:重签必须使用支持相同 entitlement 的证书