iOS中如何正确配置Info.plist以启用通知服务扩展？

阿华AIGC实验室

2026-4-2

嘿，我太懂你这种Android一路顺畅，到iOS就卡壳的憋屈感了！通知服务扩展的配置确实有不少容易踩坑的细节，我来帮你一步步梳理清楚，解决没法自动处理推送的问题。

首先：先把App Groups的一致性搞定

你提到主App的App Groups里已经有group.id.co.xxxx.app.xxxxx.onesignal，这很好，但通知服务扩展的Target必须也添加同一个App Group——这是主App和扩展共享推送数据的前提，没这一步扩展根本拿不到推送内容来处理。操作步骤：

打开Xcode，选中你的通知服务扩展Target
切换到Signing & Capabilities标签页
点击+ Capability，找到并添加App Groups
在弹出的列表里勾选和主App完全一样的那个group.id.co.xxxx.app.xxxxx.onesignal

主App的Info.plist必须添加的配置

主App这边要先把后台推送权限开起来，不然扩展也没法触发。打开主App的Info.plist，添加以下内容：

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

这个配置让App能在后台接收推送，是通知扩展工作的基础。

通知服务扩展的Info.plist优化（结合你提供的内容）

你现在的扩展Info.plist已经有了基础的核心配置，但还需要补充几个关键项来确保自动触发：

你现有配置里的NSExtensionPointIdentifier和NSExtensionPrincipalClass都是正确的，不用改
推荐添加UNNotificationExtensionInitialContentSizeRatio来设置通知的初始显示比例（避免某些场景下扩展不加载）
如果需要隐藏系统默认的通知内容、完全用自定义内容替代，可以添加UNNotificationExtensionDefaultContentHidden

补充后的完整配置大概是这样：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSExtension</key>
    <dict>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.usernotifications.service</string>
        <key>NSExtensionPrincipalClass</key>
        <string>$(PRODUCT_MODULE_NAME).NotificationService</string>
    </dict>
    <!-- 设置通知初始显示比例，可选但强烈推荐 -->
    <key>UNNotificationExtensionInitialContentSizeRatio</key>
    <real>1.0</real>
    <!-- 如果要隐藏默认通知内容，启用下面这行 -->
    <!-- <key>UNNotificationExtensionDefaultContentHidden</key>
    <true/> -->
    <!-- 如果你的推送用了自定义分类，添加分类ID数组 -->
    <!-- <key>UNNotificationExtensionCategory</key>
    <array>
        <string>你的自定义分类ID</string>
    </array> -->
</dict>
</plist>

最容易被忽略的关键：推送Payload必须带`mutable-content: 1`

这是很多人踩坑的点！如果你的推送消息里没有mutable-content: 1这个字段，iOS系统根本不会触发通知服务扩展，必须用户点击才会处理。

如果你用OneSignal推送，在推送设置的「高级选项」里找到「Mutable Content」并勾选
手动构造payload的话，要确保添加："mutable-content": 1

最后几个检查点

确保扩展的Deployment Target和主App一致（不能高于主App的版本）
检查NotificationService类的代码：必须在didReceive(_:withContentHandler:)方法里调用contentHandler返回处理后的内容，否则扩展超时后系统会显示原始通知
查看Xcode控制台的日志：如果扩展加载失败，会有相关的错误提示（比如权限问题、类找不到等），能帮你快速定位问题

按照这些步骤检查一遍，应该就能解决你没法自动处理推送的问题啦！如果还有疑问，随时说细节我再帮你排查~