一、普通消息为什么收不到离线推送？
现象：iOS 普通消息收不到离线推送。
处理：
1. 请先切换到生产环境测试：如果 App 当前处于开发环境，向苹果申请 deviceToken 可能会失败。
2. 检查 App 运行环境与证书 ID 是否对应：Xcode 直接运行的 Debug 包使用开发环境证书 ID；Archive 后的 Release 包使用生产环境证书 ID。
3. 如果客户端未获取到 deviceToken，请参见 注册时偶现不返回 deviceToken，如何处理。
二、iOS 已收到推送但没有看到通知，如何检查？
现象：排查工具显示推送已送达设备，但设备上没有弹出通知。
原因：设备的通知设置或专注模式限制了该应用通知的展示方式。
处理：
1. 检查通知设置：在“设置 > 通知”中选择该 App，确认已打开“允许通知”；在“提醒”下检查通知是否设为出现在锁定屏幕、通知中心或横幅；检查“通知推送”是否设为“定时推送摘要”，设为摘要时通知不会即时送达。参见 Apple 支持：更改 iPhone 的通知设置。
2. 检查专注模式：在“设置 > 专注模式”中查看当前开启的专注模式，确认没有将该 App 的通知静音。专注模式期间 iPhone 会推迟通知推送。参见 Apple 支持：在 iPhone 上为专注模式允许或静音通知。
三、点击通知后拿不到 ext 或无法跳转，如何处理？
现象：点击通知后拿不到 ext，或无法跳转指定页面。
原因：发送侧未设置 ext、冷热启动取 payload 的方式不同，或 Flutter iOS 端 listener 重复注册。
处理：
1. 先核对发送侧：发送消息时是否设置了 V2TIMOfflinePushInfo 的 ext 字段；未设置时 APNs payload 中没有自定义字段，客户端无法解析。自定义消息还必须设置 desc 字段才会推送。
2. 区分冷启动与热启动：冷启动（杀进程后点击通知）通过 launchOptions 获取 payload，热启动走 didReceiveNotificationResponse 回调；点击回调需在 App 启动早期注册，避免首页路由完成后才注册导致数据丢失。
3. Flutter 端：确认 listener 只注册一次，重复回调多为插件 listener 重复注册导致。
四、iOS 没有收到触达回执，如何处理？
现象：iOS 没有收到推送触达回执。
原因：未开启 Extension 统计开关，或触达数据延迟到下次登录才上报。
处理：
·上报推送触达数据，需要开启控制台开关来支持 iOS 10 的 Extension 功能，详情请参见 统计消息触达率。
·为保证上报数据在一些异常情况下不丢失，iOS 推送数据的上报会在下次登录时上报，可能会有滞后，请尝试重新登录。
五、APNs、VoIP 和 LiveActivity 有什么区别？
区别如下：
·APNs：发送通知提醒用户，集成 TIMPush。
·VoIP：音视频通话推送，集成 CallKit 和 TUICallKitVoIPExtension。
·LiveActivity：显示实时更新动态，集成 ActivityKit 和 IMSDK（iOS 16 以上支持）。
六、iOS 证书过期，如何处理？
在 IM 控制台编辑并更新对应的 .p12 证书。请勿删除后重新创建证书，否则证书 ID 会变化，已发布的旧版本需要更新配置并重新发版。
七、iOS 注册报错 errCode 3000，如何处理？
现象：iOS 注册报错 errCode 3000，提示未找到应用程序的 “aps-environment” 授权字符串。
原因：
·原因1：在 Xcode 项目中未启用推送通知权限，检查 Xcode 配置。开启方法参考：Xcode 添加 Push Notifications。
·原因2：在应用归属的 Apple ID 账号下，对应应用未勾选 Push Notifications 开启远程推送服务。可以查看描述文件是否包含 “aps-environment”，以及是否对应正确的开发环境或生产环境。开启方法参考：申请 APNs 证书。
·原因3：工程使用 XcodeGen 生成。XcodeGen 会在每次执行 xcodegen generate 时，按 project.yml 中的 entitlements 配置重新生成 .entitlements 文件。如果只在 Xcode 界面中添加了 Push Notifications，或 project.yml 的 entitlements 只配置了 path、没有配置 properties，重新生成后 aps-environment 会丢失。
处理：按对应原因逐个排查处理。
八、控制台测试提示 Token 与证书不匹配，如何处理？
现象：控制台测试工具返回 Token 与证书不匹配。
原因：iOS 推送证书 ID 和 deviceToken 都区分开发环境与生产环境，两者环境不一致时无法推送。
处理：
1. deviceToken 所属环境取决于客户端打包方式，请先确认环境是否一致：
·开发环境（Xcode 直接运行）：由 Debug 设置配置上传的证书 ID。
·生产环境（打包 ipa）：由 release 设置配置上传的证书 ID（大部分客户常把生产的证书上传到开发环境）。
2. .p12 证书可以选择开发/生产一体的证书，或者使用 .p8 证书。上传到 IM 控制台选择想要的环境即可。
九、注册时偶现不返回 deviceToken，如何处理？
现象：iOS 开发环境下，注册偶现不返回 deviceToken，或提示 APNs 请求 token 失败。
原因：获取 deviceToken 可能受网络、设备状态或 APNs 临时异常影响。
处理：可尝试通过以下方式解决：
·给手机插入 SIM 卡后使用 4G 网络测试。
·卸载重装、重启 App、关机重启后测试。
·打生产环境的包测试。
·更换其它 iOS 系统的手机测试。
十、后台报错 bad devicetoken，如何处理？
现象：收不到推送，后台报错 bad devicetoken。
原因：Apple 的 deviceToken 与当前编译环境有关，deviceToken 与证书 ID 对应的环境不匹配。
处理：请检查：
1. 接入流程中 配置推送参数 的 businessID 是否为对应环境的证书 ID。
2. 控制台创建证书检查：
·生产环境证书：上传的证书类型为 Apple Push Notification service SSL (Sandbox & Production)，并在 Archive 出 Release 包后进行测试。注意：不可在 Xcode 测试。
·开发环境证书：可使用 Xcode 直接运行 Debug 包进行测试，创建时选择正确证书即可。
十一、APNs 报错 403 InvalidProviderToken，如何处理？
现象：APNs 推送返回 403 InvalidProviderToken。
原因：使用 .p8 证书时，上报的 Token 与证书信息不匹配，导致 APNs 验证失败。
处理：请核对以下配置：
·客户端生成 regId 时，使用的 bundleId 要与服务端推送使用的 bundleId 一致。
·teamId 和 keyId 填写准确。
·证书环境正确（检查证书是否与开发环境或生产环境对应）。
十二、iOS 启动报错 Library not loaded: ImSDK_Plus，如何处理？
现象：报错 dyld: Library not loaded: ImSDK_Plus。
完整报错如下：
dyld: Library not loaded: @rpath/ImSDK_Plus.framework/ImSDK_Plus，Referenced from: /private/var/containers/Bundle/Application/xxxxx/Demo.app/Frameworks/TIMPush.framework/TIMPush，Reason: image not found
原因：因缺少 IM SDK 引起。
处理：需先执行 pod 'TXIMSDK_Plus_iOS' 或 pod 'TXIMSDK_Plus_iOS_XCFramework'，加上后再执行 pod install。
十三、XcodeGen 工程编译报错 No such module 'TIMPush'，如何处理？
现象：XcodeGen 工程编译报错 No such module 'TIMPush'。
原因： xcodegen generate 会按 project.yml 重写 project.pbxproj，清掉 CocoaPods 注入的 [CP] 脚本，导致工程不再链接 Pods（Pods/ 与 Podfile.lock 仍在，但 import TIMPush 报 No such module）。
处理：
1. 如刚修改过 project.yml，先执行 xcodegen generate。
2. 执行 pod install。
3. 使用 .xcworkspace（而不是 .xcodeproj）重新打开工程，Clean Build Folder 后编译。
建议在 CI 中固定顺序：xcodegen generate → pod install。
十四、iOS 桌面角标和 IM 未读数不一致，如何自定义角标？
iOS 默认将所有会话的未读数之和作为角标。如需自定义，请实现 onSetAPPUnreadCount 回调，并按自己的规则计算后返回角标总数。具体设置步骤参见 自定义角标。