普通消息为什么收不到离线推送?
现象:iOS 普通消息收不到离线推送。
原因:App 运行环境与证书 ID 对应的环境不一致,或设备未成功获取 deviceToken(开发环境下向苹果申请 deviceToken 可能失败)。
处理:
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。