iOS 自定义通知 UI：UNNotificationContentExtension 从配置到排错落地

做内容类、工具类应用的同学大概都遇到过这种尴尬一条推送本该是“封面图 标题 两个快捷按钮”的组合结果在通知中心里只能显示成一行标题加一行正文剩下的信息全被折叠掉了。iOS 10 引入的 UserNotifications 框架里有一块能力专门解决这个问题就是UserNotifications 自定义通知 UI核心 API 是UNNotificationContentExtension。它允许你在用户展开通知的那一刻接管通知卡片的主体区域用一整个 View Controller 去渲染任意界面——图片、进度条、列表、按钮都能放。这套机制不是新东西但因为涉及跨进程、跨 target、plist 配置和一堆隐式约束实际踩坑的人非常多。这篇内容面向已经能正常发出本地/远程通知、想把通知样式再往上抬一档的 iOS 开发者也会尽量把前置概念补齐让刚接触通知扩展的读者能跟得上。下面按“为什么这么设计—怎么落地—怎么排错—怎么保证稳”的顺序展开所有代码和配置都可以直接抄改。1. 通知自定义 UI 到底解决了什么问题1.1 系统默认样式的天花板在哪里在讨论扩展之前得先认清系统默认通知样式的边界。UNMutableNotificationContent提供的可配置项就那么多title、subtitle、body、sound、badge、attachments、userInfo、categoryIdentifier、threadIdentifier、summaryArgument。你能控制的是文字内容、一条附件图片/音频/视频、以及挂在通知底部的 action 按钮。样式层面字号、颜色、布局全部由系统决定开发者没有入口。这就导致两个很现实的问题。第一信息密度上不去。一条电商促销通知你想同时展示商品图、原价、折扣价、倒计时系统样式塞不进去。第二交互深度不够。用户收到一条“有人评论了你”的通知想直接在通知里回一句“收到”靠 action 按钮可以做但按钮是系统渲染的位置固定、样式固定最多三个还不支持自定义图标。UNNotificationContentExtension就是给这两个问题开的口子。它的本质是一个独立的 App Extension 进程系统在通知被展开时把它拉起来把你写的 View Controller 的 view 嵌进通知卡片里。你能用的东西和普通页面没区别UIImageView、UILabel、UIProgressView、UIButton、甚至一段AVPlayer。区别只在于生命周期极短、内存极紧、交互受限。这里要强调一个容易被误解的点自定义 UI 不是“替换整条通知”而是“替换通知展开后的内容区”。通知的头部应用图标、应用名、时间和底部的 action 按钮区域依然是系统的。所以设计的时候不要按整屏来想要按一个高度受限的卡片中部区域来想。1.2 三种通知扩展的分工别用错工具UserNotifications 体系里一共有三类扩展功能完全不同实际项目里经常被混用。我先把它们的分工摆清楚扩展类型对应协议什么时候执行典型用途有没有 UIService ExtensionUNNotificationServiceExtension收到远程通知、通知展示前修改内容、下载并挂载附件、端到端解密无Content ExtensionUNNotificationContentExtension用户展开通知时自定义卡片界面、播放控制、按钮交互有Action / Category无需单独扩展用户点击 action 按钮快捷操作入口系统渲染最容易搞混的是 Service Extension 和 Content Extension。前者在通知送达设备后、展示给用户前运行时间窗口只有 30 秒左右超时会被系统强杀它的产出是“一条被改过的通知内容”。后者在用户主动展开通知时运行产出是“一块界面”。两者经常配合使用Service Extension 负责把远程图片下载下来存成 attachmentContent Extension 负责把 attachment 渲染出来。我见过有同学想在 Content Extension 里发网络请求拉数据这个思路是错的。通知展开是一个瞬时的用户动作扩展进程的冷启动加上网络往返很容易让用户盯着白屏看一两秒体验极差。正确做法是把通知渲染需要的数据在推送 payload 里带全或者用 Service Extension 提前准备好Content Extension 只做“读和画”。1.3 技术选型前先问自己三个问题不是所有通知都值得上自定义 UI。我一般会先过三个判断第一这条通知的核心价值是靠“文字”传达还是靠“视觉”传达纯文本提醒日程、验证码、账单用系统样式完全够硬做自定义 UI 是给自己找维护成本。带封面图、带价格对比、带进度条的场景才值得。第二用户会不会愿意展开它自定义 UI 只在展开后可见。如果一个应用的推送常年被用户左滑清掉那做多精美的 UI 都没人看见。这类场景优先级应该放在提升推送相关性上而不是样式上。第三交互是否真的需要“在通知里完成”如果点击后跳进 App 的路径足够短action 按钮就够用了。只有那种“用户不想离开当前上下文”的操作——比如播放/暂停、标记已读、快速评分——才值得做进通知卡片。第三点尤其重要。很多团队做完自定义 UI 之后发现使用率极低回头一看用户点通知直接就进 App 了没人愿意在通知栏里操作。这不是技术问题是场景判断问题。1.4 环境与前置准备动手前确认几件事。系统版本上UNNotificationContentExtension从 iOS 10 开始提供但很多关键能力是后续版本补的iOS 12 起支持一个扩展声明多个 category、支持UNNotificationExtensionUserInteractionEnabled让卡片内的控件真正可点iOS 13 起通知卡片有了圆角和深色模式背景处理要跟着调整iOS 15 的通知摘要机制会让低优先级通知以简化样式呈现自定义 UI 不一定展示。所以最低支持版本如果低于 iOS 12交互部分要做降级。工程侧需要至少两个 target主 App 和一个 Notification Content Extension。如果还要做附件预下载再加一个 Service Extension。三者如果要共享数据必须配置 App Group因为扩展是独立进程、独立沙盒主 App 的UserDefaults.standard和文件目录在扩展里是访问不到的——这个坑后面会专门讲。真机是必须的。模拟器上通知扩展的表现和真机差异不小尤其是内存限制和展开手势。调试用的设备建议至少准备一台刘海屏机型和一台非刘海机型因为通知卡片的可用宽度不同比例算错的话在另一种机型上会露馅。2. 整体方案设计与调用时序2.1 为什么把渲染逻辑全部压在 Content Extension 里一个常见的架构分歧是通知 UI 的数据从哪来有三种常见做法——扩展里读 payload、扩展里读 App Group 共享存储、扩展里发网络请求。我的选择几乎永远是第一种复杂场景才退化到第二种第三种基本不用。原因在于进程生命周期。Content Extension 的进程是按需拉起的用户展开通知时系统 fork 一个扩展进程、加载你的二进制、实例化 View Controller、调didReceive、渲染、等待用户操作整个过程有几秒的硬性时间窗。冷启动本身就要几百毫秒如果再加上一次网络请求界面空窗期会非常明显。而 payload 是随通知一起到达的读取是纯内存操作零延迟。还有一个隐性成本扩展进程的内存上限非常紧。社区里普遍反馈的量级在 24MB 上下超过会被系统直接杀掉表现是通知卡片闪一下白然后消失日志里能看到资源超限的记录。在这个预算下你既要放 UI 框架的运行时又要放图片解码的缓冲区能省则省。所以我的一般架构是payload 里带齐所有“文字类”字段标题、副标题、价格、状态、时长等图片走 attachmentApp Group 只用来做“状态同步”比如用户在卡片里点了已读主 App 下次启动要知道这件事。2.2 一次展开动作背后的完整时序把时序理清楚后面所有配置项的意义就都能对上号了。用户在通知中心长按或下拉一条通知系统做的事大致是这样读取这条通知的categoryIdentifier在已注册的 category 定义里查它绑定了哪个 Content Extension拉起对应的扩展进程加载 storyboard 或 principal class实例化UNNotificationContentExtension的 View Controller调viewDidLoad此时 view 已经被创建但尺寸还没最终确定调didReceive(_ notification:)把整条UNNotification递给你系统按UNNotificationExtensionInitialContentSizeRatio算出内容区高度套上圆角和背景用户在卡片里操作触发didReceive(_ response:completionHandler:)或媒体回调用户收起通知或跳转 App扩展进程进入挂起/销毁。第 2 步是排查问题的关键。如果 category 没有注册、或者 payload 里的categoryIdentifier和扩展 plist 里声明的不一致第 2 步直接查不到系统就退回默认样式你能看到的只有“自定义 UI 没生效”。99% 的“我明明配了扩展但通知还是老样子”都栽在这里。第 7 步也值得琢磨。内容区高度不是你在约束里写多少就是多少而是ratio × 卡片宽度。卡片宽度又和屏幕宽度、设备方向、是否分屏有关。所以设计稿里的固定高度在代码里必须换算成比例这个换算后面第三节会给具体算式。2.3 工程结构怎么切我的习惯是在主工程里单独建一个 group 叫NotificationKit把三类东西集中管理NotificationCategory.swift所有 category 和 action 的标识符常量、注册代码NotificationPayload.swiftpayload 的字段名常量和解析结构体NotificationBuilder.swift构造UNNotificationRequest的工厂方法。扩展 target 只依赖这个 group 里的常量文件不依赖主 App 的 UI 层和网络层。这么做的好处是标识符只有一处定义主 App 注册 category 用的字符串和扩展 plist 里填的字符串不会出现手误对不上——这个错误极其常见而且排查起来很费时间因为编译器完全帮不上忙。另外提醒一句扩展 target 的Info.plist里那个 category 键值是字符串字面量Xcode 不会给你任何校验。我的做法是在扩展的didReceive里第一行打一条日志把notification.request.content.categoryIdentifier打出来和 plist 里的值肉眼对一遍。这个习惯帮我省过很多次时间。3. 从零创建自定义通知 UI 的完整流程3.1 新建 target 与 Info.plist 的关键键值在工程里新建 target模板选 Notification Content Extension。模板会自动生成四样东西一个NotificationViewController.swift已经声明了UNNotificationContentExtension协议、一个MainInterface.storyboard、一个Info.plist、以及一个Info.plist里预置好的NSExtension字典。真正决定行为的是Info.plist里NSExtension → NSExtensionAttributes下的那几个键。它们的含义和取值范围如下键名类型作用常见取值UNNotificationExtensionCategoryString 或 Array绑定哪个 category 使用本扩展与代码里注册的 category 标识符一致UNNotificationExtensionInitialContentSizeRatioNumber内容区高度与卡片宽度的比例0.3 ~ 0.6 之间多数场景 0.4 上下UNNotificationExtensionDefaultContentHiddenBoolean是否隐藏系统默认的标题/正文自定义 UI 里有自己的标题就设 YESUNNotificationExtensionUserInteractionEnabledBoolean卡片内控件是否响应点击iOS 12需要按钮就设 YESUNNotificationExtensionMediaPlayPauseButtonTypeString系统媒体按钮样式none/play/playpauseUNNotificationExtensionMediaPlayPauseButtonFrameString媒体按钮位置尺寸{{10,10},{30,30}}这样的字符串格式UNNotificationExtensionMediaPlayPauseButtonTintColorString媒体按钮着色十六进制色值写成 plist 大致是这样keyNSExtension/key dict keyNSExtensionAttributes/key dict keyUNNotificationExtensionCategory/key stringcontentCard/string keyUNNotificationExtensionInitialContentSizeRatio/key real0.42/real keyUNNotificationExtensionDefaultContentHidden/key true/ keyUNNotificationExtensionUserInteractionEnabled/key true/ /dict keyNSExtensionMainStoryboard/key stringMainInterface/string keyNSExtensionPointIdentifier/key stringcom.apple.usernotifications.content-extension/string /dictNSExtensionPointIdentifier这一项模板会自动填好手写时千万不要改它是系统识别扩展类型的唯一依据。填错了扩展根本不会被拉起而且不会有任何报错。UNNotificationExtensionCategory在 iOS 12 之后可以写成数组一个扩展服务多个 categorykeyUNNotificationExtensionCategory/key array stringcontentCard/string stringcontentCardCompact/string /array注意这里的取舍一个扩展服务多个 category意味着多个场景共用同一套界面逻辑靠categoryIdentifier分支渲染。好处是包体积小、维护点集中坏处是界面差异大的时候代码会变成 if-else 泥潭。我的分界线是如果两个场景的布局结构相同、只是字段不同就合并如果布局本身不同比如一个是横排图片卡一个是竖向进度条就拆成两个扩展。3.2 注册 Category 与 Action 的正确姿势Category 必须在系统有机会展示通知之前注册好。最稳的位置是application(_:didFinishLaunchingWithOptions:)里而且是同步执行不要放到异步回调里。原因在于冷启动路径用户从通知中心点开一条通知系统会先把 App 拉起来如果它没在运行然后再处理响应。如果注册代码跑在一个异步任务里可能系统处理响应时 category 还没注册完UNNotificationResponse里的 action 信息就会缺失。import UserNotifications enum NotificationCategoryID { static let contentCard contentCard } enum NotificationActionID { static let markRead markRead static let openDetail openDetail } func registerNotificationCategories() { let markRead UNNotificationAction( identifier: NotificationActionID.markRead, title: 标记已读, options: [] ) let openDetail UNNotificationAction( identifier: NotificationActionID.openDetail, title: 查看详情, options: [.foreground] ) let category UNNotificationCategory( identifier: NotificationCategoryID.contentCard, actions: [markRead, openDetail], intentIdentifiers: [], options: [.customDismissAction] ) UNUserNotificationCenter.current().setNotificationCategories([category]) }这里几个细节值得说。options传空数组表示点击后 App 在后台被唤起、通知自动消失传.foreground则会拉起 App 到前台。.customDismissAction加在 category 上是为了在用户手动清掉通知时也能收到回调UNNotificationDismissActionIdentifier做数据统计或者状态回滚时会用到。intentIdentifiers是给 Siri 集成用的普通场景留空数组即可。不要传nil虽然文档里是可选的但某些系统版本对nil的处理有差异留空数组最稳。还有一个经常被忽略的点setNotificationCategories是覆盖式的不是追加式。如果你在另一个模块里也调了一次并传了别的 category 数组之前注册的会被清掉。所以整个 App 里这个方法应该只有一处调用把全部 category 组装好一次性设置。我见过一个项目里推送模块和 IM 模块各写了一份注册代码结果后启动的模块把前一个的 category 冲掉了表现为某类通知的按钮时有时无查了很久。3.3 发通知与 payload 的拼装细节自定义 UI 能不能显示出来第一道关卡在发送端。核心只有一句content.categoryIdentifier必须等于扩展 plist 里声明的那个字符串。func postContentCardNotification() { let content UNMutableNotificationContent() content.title 今日推荐 content.body 你关注的专栏更新了 3 篇内容 content.categoryIdentifier NotificationCategoryID.contentCard content.userInfo [ author: 某创作者, readCount: 1280, duration: 320 ] content.threadIdentifier column-update let trigger UNTimeIntervalNotificationTrigger(timeInterval: 5, repeats: false) let request UNNotificationRequest( identifier: UUID().uuidString, content: content, trigger: trigger ) UNUserNotificationCenter.current().add(request) }userInfo是 payload 里最灵活的部分自定义 UI 需要的所有业务字段都往这塞。值的类型只支持 plist 支持的类型String、Number、Bool、Date、Array、Dictionary。别塞自定义对象序列化会在添加请求时失败而且add的 error 回调经常被忽略表现就是“通知发不出去但也没报错”。附件部分有个必踩的坑func attachCoverImage(to content: UNMutableNotificationContent) { guard let source Bundle.main.url(forResource: cover, withExtension: jpg) else { return } // 必须拷贝到可写目录不能直接用 bundle 里的只读文件 let dest FileManager.default.temporaryDirectory .appendingPathComponent(UUID().uuidString) .appendingPathExtension(jpg) do { try FileManager.default.copyItem(at: source, to: dest) let attachment try UNNotificationAttachment( identifier: cover, url: dest, options: [UNNotificationAttachmentOptionsThumbnailClippingRectKey: CGRect(x: 0, y: 0, width: 1, height: 1).dictionaryRepresentation] ) content.attachments [attachment] } catch { print(attachment 构建失败: \(error)) } }UNNotificationAttachment的url参数要求文件位于 App 可写的容器内直接传 bundle 内的资源路径会抛错。系统在添加附件时会把文件复制到它自己的存储区所以临时目录里的副本在添加完成后就可以删了不删也只是占点空间。远程推送的话payload 里对应的是aps.category同时要带上mutable-content: 1才会走 Service Extension{ aps: { alert: { title: 今日推荐, body: 你关注的专栏更新了 3 篇内容 }, category: contentCard, mutable-content: 1, sound: default }, author: 某创作者, readCount: 1280 }3.4 内容区高度比例怎么算才不翻车UNNotificationExtensionInitialContentSizeRatio是整个配置里最容易算错的一项。它不是“高度占屏幕的比例”而是“内容区高度 ÷ 内容区宽度”。内容区宽度在 iPhone 竖屏下约等于屏幕宽度减去左右边距实际可用宽度会随系统版本变化所以按屏幕宽度估算会有几到十几点的偏差但作为设计基准够用。换算方式设计稿上内容区想做到 180pt 高目标机型屏幕宽 390pt那么 ratio ≈ 180 / 390 ≈ 0.46。这个比例在不同宽度的设备上会等比缩放320pt 宽的设备上高度变成约 147pt430pt 宽的设备上变成约 198pt。等比缩放的好处是视觉比例一致坏处是如果你在布局里写死了某些元素的高度比如固定 40pt 的按钮小屏上就会挤。我的处理办法是把 ratio 定在 0.4 到 0.5 之间然后界面内部全部用 Auto Layout 相对约束不写死高度。图片用contentMode .scaleAspectFill加clipsToBounds文字用numberOfLines 0让它自己撑容器用等比例约束跟随。还有一个上限问题。内容区高度不是无限的实测下来超过屏幕高度的一大半就会被截断具体数值随系统版本变化。所以别指望在通知卡片里放一个长列表那不现实。真要展示多条内容用UNNotificationServiceExtension合并成一条摘要更合适。iPad 上要特别注意。通知卡片的宽度和 iPhone 完全不同而且分屏状态下还会变。如果 App 支持 iPadratio 一定要在 iPad 上实测一遍我遇到过按 iPhone 算好的比例在 iPad 上把内容压成一条缝的情况。3.5 didReceive 里的渲染逻辑与 completionHandlerView Controller 的骨架长这样import UIKit import UserNotifications import UserNotificationsUI final class NotificationViewController: UIViewController, UNNotificationContentExtension { IBOutlet weak var coverImageView: UIImageView! IBOutlet weak var titleLabel: UILabel! IBOutlet weak var metaLabel: UILabel! IBOutlet weak var progressView: UIProgressView! override func viewDidLoad() { super.viewDidLoad() view.backgroundColor .clear coverImageView.layer.cornerRadius 8 coverImageView.clipsToBounds true } func didReceive(_ notification: UNNotification) { let content notification.request.content titleLabel.text content.title metaLabel.text content.body let info content.userInfo if let readCount info[readCount] as? Int { metaLabel.text \(content.body) · \(readCount) 人已读 } if let duration info[duration] as? Double, duration 0 { progressView.isHidden false progressView.progress 0.35 } else { progressView.isHidden true } loadCover(from: content.attachments) } private func loadCover(from attachments: [UNNotificationAttachment]) { guard let attachment attachments.first else { return } let url attachment.url let accessing url.startAccessingSecurityScopedResource() defer { if accessing { url.stopAccessingSecurityScopedResource() } } if let data try? Data(contentsOf: url), let image UIImage(data: data) { coverImageView.image image } } }几个实现上的注意点。viewDidLoad里把背景设成.clear让系统自己的卡片背景透出来这样圆角和材质能保持一致如果你自己画一个不透明背景深色模式下容易出现色差。图片读取优先用Data(contentsOf:)而不是UIImage(contentsOfFile:)因为后者在某些系统版本上对安全作用域路径的处理不一致前者更稳。didReceive(_:)里不要做任何耗时操作。图片解码本身就有成本如果附件是大图建议在 Service Extension 阶段就压缩到合理尺寸再挂载别指望在 Content Extension 里现场处理。我一般把通知用图的短边控制在 600px 以内JPEG 质量 0.8单张控制在 100KB 以下这个规格在视网膜屏上显示效果和加载速度都能接受。带交互的回调版本是另一个方法func didReceive(_ response: UNNotificationResponse, completionHandler completion: escaping (UNNotificationContentExtensionResponseOption) - Void) { switch response.actionIdentifier { case NotificationActionID.markRead: titleLabel.text 已标记为已读 // 通知保持展开用户可以继续操作 completion(.doNotDismiss) case UNNotificationDefaultActionIdentifier: completion(.dismissAndForwardAction) default: completion(.dismiss) } }UNNotificationContentExtensionResponseOption有三个值语义差别很大必须理解清楚.dismiss收起通知不触发任何后续动作.dismissAndForwardAction收起通知并把这次响应转发给主 App 的userNotificationCenter(_:didReceive:withCompletionHandler:).doNotDismiss通知保持展开状态什么都不发生。.doNotDismiss是做“原地状态切换”的关键——用户点了“标记已读”卡片上立刻变成已读样式通知不消失用户还能继续点别的。但如果你的操作需要跳转 App就必须用.dismissAndForwardAction否则主 App 收不到通知。这里有个必须提醒的点completion必须被调用而且只能调用一次。忘了调系统会一直等用户看到的表现是按钮点下去没反应调两次会触发未定义行为通常是崩溃。4. 交互、媒体控制与跨进程通信4.1 用系统媒体按钮还是自己画按钮通知卡片里的播放控制有两条路。一条是用系统提供的媒体按钮通过 plist 里的UNNotificationExtensionMediaPlayPauseButtonType配置另一条是自己放UIButton靠UNNotificationExtensionUserInteractionEnabled打开交互。系统媒体按钮的优势是稳位置由系统绘制不受内容区裁剪影响播放状态由系统维护你只需要实现mediaPlay()、mediaPause()、mediaPlayPause()、mediaStop()这几个回调。劣势是只有一个按钮样式和位置的自定义空间很小只能调 frame 和 tintColor。extension NotificationViewController { func mediaPlay() { // 通知系统播放器已进入播放态 player.play() progressView.progress 0 } func mediaPause() { player.pause() } func mediaPlayPause() { if player.isPlaying { player.pause() } else { player.play() } } func mediaStop() { player.stop() } }媒体按钮的 frame 是字符串格式写{{x,y},{width,height}}注意这是字符串而不是字典写错了 plist 解析会失败导致扩展不加载。tintColor 用#RRGGBB形式。这两个配置项我建议能不动就不动让系统用默认值兼容性最好。自己画按钮的场景是需要多个控制项上一首/播放/下一首或者按钮要带特定的图标和文字。这种做法的前提是UNNotificationExtensionUserInteractionEnabled设为YES而且只在 iOS 12 以上生效。低版本系统上按钮就是一张图片点不动所以如果最低版本低于 12用系统媒体按钮反而更保险。4.2 卡片内交互的边界在哪里即使打开了用户交互卡片内的控件能力也不是完整的。触摸事件能到你的 view 上但一些系统级手势会优先被拦截比如从卡片边缘下拉收起通知。实际体验下来点击类操作按钮、开关没问题拖拽类操作滑动删除、长按拖动会很不稳定。另一个限制是卡片里不要放需要持续运行的东西。AVPlayer播放音视频在通知里是可以的但一旦通知被收起扩展进程随时可能被挂起播放会中断。所以这类功能的定位应该是“预览”而非“完整播放”超过 30 秒的内容建议引导用户进 App。还有一个容易忽略的点卡片内控件的点击区域要留够。通知卡片的整体高度有限按钮做小了用户根本点不准。我的经验是按钮的点击热区不小于 44×44pt视觉尺寸可以小但用contentEdgeInsets或者透明视图把热区撑起来。4.3 App Group 是跨进程通信的唯一正道Content Extension 和主 App 是两个进程、两个沙盒。扩展里访问UserDefaults.standard拿到的是扩展自己的存储和主 App 完全隔离。文件目录同理。想共享数据必须配置 App Group。配置步骤是在主 App 和扩展两个 target 的 Signing Capabilities 里都加上 App Groups勾选同一个 group 标识符形如group.你的反向域名.共享区。然后代码里用这个 group 标识符拿共享容器enum SharedStore { static let suiteName group.com.example.shared static var defaults: UserDefaults { UserDefaults(suiteName: suiteName) ?? .standard } static var containerURL: URL? { FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: suiteName) } }一个真实的使用场景用户在通知卡片里点了“标记已读”卡片内部立刻变色同时把这条内容的 id 写进共享UserDefaults的一个待同步数组里。主 App 下次启动时读这个数组批量把状态同步到服务端然后清空数组。整个过程不需要扩展发网络请求也不需要在卡片里等结果。这里有个坑要提醒共享UserDefaults的写入不是实时的。扩展进程写完主 App 立刻读可能读不到因为底层有缓存和同步延迟。如果两个进程的读写时序很近写完手动调一次synchronize()虽然官方说已废弃但在这种跨进程场景下仍然有用或者改用文件 文件协调的方式。我的做法是接受这个延迟因为真实场景里主 App 读取的时间点通常在几分钟之后。文件共享也是同理扩展要读的图片、配置 JSON 都放在containerURL下面路径结构两边用同一套常量拼。千万别在两边各写一份路径拼接代码早晚会对不上。5. 调试与常见问题排查实录5.1 扩展进程怎么调试扩展不能像普通 App 一样直接 Run。开发工具里选中扩展的 scheme 运行时它会提示你选择一个宿主 App 来启动。更常用的方式是“附加到进程”先把 App 跑起来发一条通知长按展开然后在调试菜单里按进程名附加。扩展进程的名字就是扩展 target 的可执行文件名通常是你的Target名。附加成功的标志是能在扩展代码里打断点。如果附加不上检查两件事一是设备上扩展是不是真的被拉起来了说明 category 没匹配上二是扩展的构建配置里有没有开启调试符号。日志方面扩展里的print会输出到设备的控制台用系统的日志工具能看到。我习惯在didReceive和viewDidLoad各打一条带时间戳的日志排查“界面为什么没出来”的时候非常有用——有日志说明扩展被拉起来了问题在渲染没日志说明扩展压根没启动问题在 category 匹配。5.2 问题速查表下面这张表是我这些年攒下来的按出现频率排序现象最可能的原因排查动作通知完全没变化还是系统样式category 未注册或 payload 里的值和 plist 不一致打印content.categoryIdentifier与 plist 逐字符比对展开后是一片空白storyboard 没设置、view 背景透明且无内容、ratio 为 0检查NSExtensionMainStoryboard拼写临时给 view 加个背景色内容区高度不对被压扁或截断ratio 按高度占比算成了宽高比、没考虑设备宽度差异按高度 ÷ 宽度重算在两种宽度机型上实测卡片里的按钮点不动UNNotificationExtensionUserInteractionEnabled没开或系统版本低于 12检查 plist 布尔值确认测试机版本图片不显示attachment 用了 bundle 只读路径、内存超限被 kill改成拷贝到临时目录观察是否伴随进程退出日志点按钮后主 App 没收到回调completion 用了.dismiss而不是.dismissAndForwardAction改 completion 参数冷启动后 category 丢失注册代码在异步回调里、或被子模块覆盖移到启动方法同步执行全局只注册一次深色模式下文字看不清硬编码了黑色文字或白色背景改用语义色背景设.clear通知摘要里没有自定义 UI系统摘要机制对低优先级通知做简化展示提升通知的打断级别或接受该场景降级扩展一闪就消失内存超限或didReceive抛异常精简图片尺寸检查有没有强解包5.3 几个我踩过的坑第一个坑是 storyboard 里的根视图约束。我一开始把内容区的高度约束写成了固定 180pt结果在小屏设备上比例算出来只有 147pt约束冲突界面直接错乱。后来改成全部相对约束根视图不设高度让系统按 ratio 给内部元素用topAnchor/bottomAnchor相对排布才彻底解决。第二个坑是扩展进程复用带来的状态残留。系统会缓存扩展进程同一个进程可能连续服务多条通知。如果你在didReceive里只更新了部分 UI没重置上一次的状态第二条通知就会显示成“半新半旧”。解决办法是在didReceive开头把所有可能变化的 UI 元素重置一遍别指望系统给你一个干净实例。第三个坑是调试期发测试通知太慢。每改一次代码要重新编译、安装、发通知、展开一轮下来一分钟。我的加速办法是写一个调试入口点击后立刻发一条 5 秒后的本地通知同时把测试数据的构造代码单独抽出来改数据不用改逻辑。另外把UNTimeIntervalNotificationTrigger的间隔调到最小1 秒即可别设成几十秒。第四个坑是关于UNNotificationExtensionDefaultContentHidden的理解。我原以为设为YES就是把系统的标题正文全藏掉实际上它只影响展开后的内容区顶部那一块通知折叠状态下的标题正文依然由系统渲染。所以设计上要保证“折叠态”和“展开态”在视觉上是连贯的不能折叠时是“今日推荐”展开后变成完全无关的另一套信息。6. 性能、内存与版本兼容的落地建议6.1 内存预算怎么花前面提到扩展进程的内存上限在 24MB 量级这个数字不是官方文档写死的而是社区反复实测的经验值不同系统版本略有浮动。在这个预算下我的一般分配是图片解码占大头控制在 8MB 以内UI 和运行时占 10MB 左右留几 MB 余量应对系统波动。控住图片内存的办法很直接限制解码后的像素总量。一张 1200×1200 的图解码后占 1200×1200×4 字节 ≈ 5.5MB两张就超了。所以通知用图我统一压到 600×600 以内解码后约 1.4MB放两三张也安全。压缩的时机放在 Service Extension 或者发送端别在 Content Extension 里现压。还有一个隐蔽的内存消耗点是字体和富文本。NSAttributedString带自定义字体会把字体文件加载进内存一个中文字体动辄几 MB。通知里能用系统字体就用系统字体必须用品牌字体的场景只加载用到的那一个字重。6.2 版本兼容要拉一张矩阵不同 iOS 版本在通知 UI 上的行为差异比想象中大上线前建议按这张表过一遍能力起始版本降级策略自定义内容区iOS 10低版本降级为系统样式加 action 按钮卡片内控件可交互iOS 12低版本隐藏按钮改走 action一个扩展绑定多个 categoryiOS 12低版本拆成多个扩展或合并界面深色模式与圆角iOS 13低版本硬编码浅色背景注意色差通知摘要简化展示iOS 15提高打断级别或接受摘要态无自定义 UI通知权限细化iOS 15申请权限时按需请求别一次全要iOS 15 的通知摘要值得单独说一句。系统会把判定为“非紧急”的通知收进摘要按时间批量展示这个状态下自定义 UI 是不出现的用户看到的是系统简化后的样式。如果你的通知承载了关键操作比如播放控制要考虑通过打断级别把它标记为时效性通知或者在文案上引导用户展开。这个策略要结合产品定位来定滥用时效性标记会被系统降权。6.3 上线前的自查清单最后一轮检查我一般会这么做按顺序过先在最低支持版本的真机上发一条通知确认展开后是系统样式还是自定义样式——这一步验证 category 链路是否通。然后在最新系统上再发一条确认圆角、深色模式、动态字体都正常。接着把系统语言切成英文看文案有没有被截断或者布局错位通知卡片的宽度在英文环境下对长单词更敏感。再往后是压力测试连续发五条通知逐条展开看扩展进程复用有没有状态残留把设备内存压到比较紧张的状态多开几个大应用再展开通知看会不会因为内存被 kill。最后是异常路径断网状态下展开、附件下载失败的情况下展开、payload 缺字段的情况下展开确认界面不会崩、不会白屏。这套流程走完大概半小时但能挡掉绝大多数线上问题。通知扩展这类功能的麻烦之处在于它出问题的时候用户不会给你反馈用户只会觉得“这个 App 的推送不好看”然后默默关掉通知权限。所以宁可上线前多花点时间。我个人在实际项目里的体会是自定义通知 UI 的价值不在于“炫技”而在于把一条通知从“告知”变成“可操作”。做之前先想清楚用户在这个卡片里到底想完成什么动作如果答案是“没有动作只想看一眼”那系统样式就是最好的选择。真正值得做的场景其实不多但做对了的那几个对推送点击率的提升是肉眼可见的。