Expo 推送通知完整教程：从权限到真机第一条通知

Expo 推送通知完整教程从权限到真机第一条通知【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo用户装了你的 App 之后很久没再打开你希望它能主动喊一声把人找回来——这正是推送通知要解决的问题。在 Expo 体系里这件事由expo-notifications库承担应用先向用户要权限再拿到一个设备专属的令牌服务端凭令牌把消息发下去最终由操作系统把横幅显示在屏幕上。这条链路里每一环都有对应的配置和代码下面按顺序拆开讲。 先把链路讲清楚权限、令牌、下发、本地处理整个过程分四步理解了它后面排错就不慌。第一步是权限。iOS 和 Android 都规定 App 不能默认弹通知必须先征求用户同意。所以代码里要先查询权限状态未授权就发起请求用户拒绝的话后面全部免谈。第二步是设备令牌。权限通过后App 向系统注册自己的推送通道系统返回一串唯一标识。在 Expo 里你拿到的是ExpoPushToken底层对应 Android 的 FCM 令牌和 iOS 的 APNs 令牌它相当于这台设备在推送网络里的门牌号。把这个令牌存到你的服务端以后发消息就发给它。第三步是消息下发。你把令牌和消息内容标题、正文、附加数据POST 给 Expo 推送服务的接口Expo 服务器再把消息转交给 FCM 或 APNs由厂商通道把消息推到设备。这一步是服务端行为和 App 本身跑不跑没关系。第四步是本地处理它取决于 App 当前处于什么状态。App 在前台时通知不会直接弹出来而是交给你注册的 JS 监听器由你决定怎么展示横幅、角标、还是完全自定义 UIApp 在后台或已被杀掉时则由操作系统直接弹横幅和通知中心条目App 本身不参与渲染。用户点击通知时无论哪种状态都会再触发一个响应监听器这是做深链跳转的入口。更细的状态行为表可以参考 通知类型与行为说明。 动手前的准备装依赖、配插件、备凭据下面四样东西在写第一行业务代码之前就要准备好缺一样都会在最意想不到的地方报错。1. 安装 JS 侧依赖。expo-notifications是通知 API 本体expo-device用来判断当前是真机还是模拟器expo-constants用来读取项目配置后面取projectId会用到npx expo install expo-notifications expo-device expo-constants2. 在app.json里注册插件。这一行让 Expo 在生成原生工程时自动写好通知相关的原生配置省掉手改 Android 和 iOS 工程的步骤{ expo: { plugins: [expo-notifications] } }3. Android 凭据FCM。Google 规定只有持 Firebase 项目凭据的 App 才能收 FCM 推送。你需要一个 Firebase 项目的google-services.json通过eas credentials上传到 Expo 项目。具体步骤见 FCM 凭据配置文档。4. iOS 凭据APNs 推送密钥。需要 Apple Developer 账号推送密钥push key由 EAS 在eas credentials流程里帮你生成和管理。如果凭据过期或丢失走同一流程重新生成即可。两个平台凭据的完整说明在 推送配置文档遇到开发模式能收、正式包收不到这类问题八成是这一节没做对。另外提一句如果只是想先看一个能跑的通知示例仓库里带了一个现成的apps/notification-tester/应用可以克隆下来跑一遍再回来写自己的代码git clone https://gitcode.com/GitHub_Trending/ex/expo 跑通第一条通知的最小步骤第 1 步构建开发包上真机。这里有个绕不开的限制——推送通知必须在真机上验证。模拟器没有真实的推送通道SDK 53 起 Expo Go 也不内置推送能力所以要用开发构建development build或正式构建别指望 Expo Go 能跑通。Android 本地开发构建可以这样起npx expo run:androidiOS 同理npx expo run:ios要发版就eas build。第 2 步拿令牌。这段代码做三件事确认是真机、拿到权限、换取ExpoPushToken。启动 App 时执行一次把返回的令牌存到后端即可。import * as Notifications from expo-notifications; import * as Device from expo-device; import Constants from expo-constants; async function registerForPushNotificationsAsync() { if (!Device.isDevice) { alert(必须在真机上测试推送); return; } const { status } await Notifications.getPermissionsAsync(); const finalStatus status granted ? status : (await Notifications.requestPermissionsAsync()).status; if (finalStatus ! granted) { alert(未获得通知权限); return; } const projectId Constants.expoConfig?.extra?.eas?.projectId ?? Constants.easConfig?.projectId; return (await Notifications.getExpoPushTokenAsync({ projectId })).data; }第 3 步发一条消息。拿到令牌后任何能发 HTTP 请求的地方都可以把它 POST 给 Expo 推送接口不需要自建推送服务器。这里顺手在 App 里写个按钮发给自己async function sendPushNotification(token) { const res await fetch(https://exp.host/--/api/v2/push/send, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ to: token, title: 你好, body: 第一条推送 }), }); console.log(await res.json()); // 返回 status确认消息已被接受 }返回的status: ok只说明 Expo 服务收到了不代表设备已显示真正的投递结果要看推送回执详见 发送通知文档。第 4 步验证。除了从 App 内部发你也可以用 Expo 的通知工具网页发测试消息方便把发和收分开调试。把设备切到后台等几秒横幅应该就会弹出来。⚠️ 真机上最容易卡住的几个地方现象在模拟器上死活收不到通知。原因模拟器的推送通道不完整且 Expo Go 从 SDK 53 起不支持推送。 解法用开发构建 真机。这不是代码问题不用改任何逻辑。现象getExpoPushTokenAsync迟迟不返回。原因iOS 上取令牌依赖设备与 APNs 服务器的注册设备没网、飞行模式、或网络环境异常时它会一直挂着Apple 明确说这不是错误状态。 解法先确认设备网络正常再重试App 侧不要把它当异常打断流程。现象开发时能收到eas build的正式包收不到。原因正式包用的是你项目的凭据而开发模式可能还在用 Expo 侧的默认配置。生产凭据没配好下发直接失败。 解法跑eas credentials补齐对应平台的推送凭据iOS 是 push keyAndroid 是 FCM然后重新构建。现象Android 上通知时灵时不灵。原因发送时的priority太低系统会按正常优先级处理可能被压缩。 解法在消息体里加priority: highAndroid 的即时展示概率最高。现象Android 小图标是一个灰色或白色方块。原因你提供的通知小图标不符合 Google 的硬性要求——必须是纯白图形加透明背景。 解法换一张纯白小图标资源这个限制和 Expo 无关是系统层面的。更多长尾问题比如 iOS 报No valid aps-environment entitlement都收录在 推送 FAQ。 三个常用的进阶用法点击通知跳转到对应页面。用户点通知时触发响应监听器把跳转参数放在消息的data字段里点击后从响应里读出来即可const sub Notifications.addNotificationResponseReceivedListener(response { const data response.notification.request.content.data; if (data?.screen) router.navigate(data.screen); }); return () sub.remove();控制 App 在前台时的展示行为。默认行为可以完全接管比如只弹横幅不响铃Notifications.setNotificationHandler({ handleNotification: async () ({ shouldShowBanner: true, shouldShowList: true, shouldPlaySound: false, shouldSetBadge: false, }), });自定义声音。把音频文件打进应用资源然后在发送的消息里指定sound字段iOS 用不带扩展名的文件名。想先听效果可以参考文档里的 自定义声音章节。监听器的完整参数和返回结构建议通读一遍 接收通知文档尤其是 App 被杀后靠点击通知冷启动的场景要尽早注册监听器。推送这条链路环环相扣权限、令牌、凭据、构建方式任何一环缺位都会表现为收不到。把上面四步走通后剩下要做的就是按 App 的实际需求去调展示和跳转逻辑。细节问题可以直接查 推送配置 和 FAQ 两篇官方文档。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考