在 Next.js 中集成 Firebase Cloud Messaging 实现 Web 推送通知【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js导读本文以 with-firebase-cloud-messaging 官方示例为蓝本讲解如何在 Next.js 应用中集成 Firebase Cloud MessagingFCM向浏览器用户发送 Web 推送通知。示例覆盖从 Service Worker 注册、Firebase 初始化到获取/缓存设备 Token 的完整链路读完本文你将能基于该示例快速搭建一个可请求通知权限、获取 FCM 注册 Token、并为后续服务端推送做好铺垫的前端工程。示例概览与目录结构这是一个基于 Pages Router 的最小示例整体工程由 4 个核心文件构成职责划分非常清晰文件职责pages/index.js首页组件挂载时触发 FCM 初始化utils/webPush.js封装 Firebase 初始化、请求通知权限与获取 Token 的逻辑public/firebase-messaging-sw.jsFCM 所需的 Service Worker用于接收后台推送消息package.json声明firebase、localforage等运行依赖从目录规划可以推断其运行流程浏览器加载页面 →pages/index.js触发初始化 →utils/webPush.js完成权限申请与 Token 获取 → Service Worker 常驻后台等待消息推送。这种“页面 工具模块 Service Worker”三层结构也方便你后续在 App Router 中迁移使用。安装与初始化项目示例 README 提供了三种包管理器的一键创建方式任选其一即可npx create-next-app --example with-firebase-cloud-messaging with-firebase-cloud-messaging-appyarn create next-app --example with-firebase-cloud-messaging with-firebase-cloud-messaging-apppnpm create next-app --example with-firebase-cloud-messaging with-firebase-cloud-messaging-app三种命令等价均通过create-next-app拉取本示例模板并生成独立应用目录with-firebase-cloud-messaging-app。创建完成后进入目录安装依赖即可本地启动cd with-firebase-cloud-messaging-app npm install # 或 yarn / pnpm install npm run dev从 package.json 可见除 Next.js 与 React 外本示例额外引入了两个关键依赖firebase^7.6.2提供 Firebase App 初始化与 Messaging 能力localforage^1.7.3在浏览器端用 IndexedDB/WebSQL/localStorage 优雅降级地持久化 FCM Token避免每次刷新页面都重复申请。dev、build、start三个脚本对应标准的本地开发、生产构建与生产启动流程。配置你自己的 Firebase 凭据示例中硬编码的 Firebase 配置均为占位符实际使用时需要替换为你自己的 Firebase 项目信息。README 明确要求在两处文件同时设置messagingSenderId实际上需要统一替换的配置共有四项firebase.initializeApp({ apiKey: YOUR-API-KEY, projectId: YOUR-PROJECT-ID, messagingSenderId: YOUR-SENDER-ID, appId: YOUR-APP-ID, });替换位置分别位于 utils/webPush.js 的init方法以及 public/firebase-messaging-sw.js 的firebase.initializeApp调用。Service Worker 中的初始化必须独立进行一次因为 Service Worker 运行在独立的全局上下文里无法共享页面脚本中的 Firebase 实例。这些值可以在 Firebase 控制台的“项目设置 → 常规 → 您的应用”中找到。需要留意这里的配置对象不带authDomain、storageBucket等字段是刻意保持最小集——Messaging 场景下这些字段并非必需但你完全可以在两处补全完整配置。页面侧的初始化细节utils/webPush.js 是示例的核心暴露了一个firebaseCloudMessaging对象其逻辑分三步幂等防重tokenInlocalforage()先从localforage读取键为fcm_token的缓存。若已存在 Tokeninit()直接return false避免每次进入页面都重复向用户弹权限请求获取权限与 Token调用firebase.messaging().getToken()。若浏览器尚未授予通知权限示例先显式调用Notification.requestPermission()请求授权持久化 Token拿到 Token 后写入localforage并console.log(fcm_token, token)输出便于开发期在控制台核对整个过程包裹在 try/catch 中失败会打印错误。调用入口在 pages/index.jsuseEffect(() { firebaseCloudMessaging.init(); }, [])即组件挂载后执行一次。将其放在useEffect而非渲染函数体内是必要的——该逻辑只应在客户端运行依赖浏览器 API而 Pages Router 的页面会先经过服务端渲染。一个值得注意的健壮性设计示例把“页面脚本里发起firebase.messaging()”与“Service Worker 里调用firebase.messaging()”分开初始化两者各自获得消息处理能力。前端页面侧的getToken()负责在页面激活时建立推送通道Service Worker 侧的firebase.messaging()即使页面关闭后仍能接收系统级推送。Service Worker 的配置细节public/firebase-messaging-sw.js 位于public目录会被 Next.js 原样静态发布。文件顶部通过importScripts从 Google CDN 加载 Firebase 的 App 与 Messaging SDK/* global importScripts, firebase */ importScripts(https://www.gstatic.com/firebasejs/7.9.1/firebase-app.js); importScripts(https://www.gstatic.com/firebasejs/7.9.1/firebase-messaging.js); firebase.initializeApp({ apiKey: YOUR-API-KEY, projectId: YOUR-PROJECT-ID, messagingSenderId: YOUR-SENDER-ID, appId: YOUR-APP-ID, }); firebase.messaging();关键点在于firebase.messaging()的注册必须在后台消息事件挂接之前生效。若示例继续扩展可在其后追加messaging.onBackgroundMessage用self.registration.showNotification在应用处于后台时展示通知。这里的 SDK 版本7.9.1与页面侧package.json中的firebase^7.x保持同一大版本升级时需注意两侧版本同步。同时示例文件使用了/* global importScripts, firebase */注释来声明全局变量避免编辑器对 Service Worker 作用域内无导入的全局符号报错。Firebase Messaging 要求 Service Worker 的注册名严格为firebase-messaging-sw.js默认约定这正是该文件被命名为firebase-messaging-sw.js的原因。部署到云端示例 README 将部署方式指向 Vercel并引用 Next.js 官方部署文档 17-deploying.mdx。部署前请确认两点以确保推送可用生产环境需使用 HTTPS浏览器通知权限 API 仅在安全上下文可用Vercel 默认提供把两处 Firebase 凭据占位符替换为真实值后再执行next build与部署避免将占位配置发布上线。对于自建服务器场景可直接使用npm run build npm run start启动生产模式。由于示例的 FCM 逻辑全部运行在客户端useEffect 浏览器 SDK部署时无需特殊配置 Server Action 或 API 路由若后续需要服务端触发推送再引入firebase-admin并通过 Route Handler见 15-route-handlers.mdx暴露发送接口即可。如何真正发送一条通知本示例 README 只完成了“接收端”基建并指引读者查阅 Firebase 官方“首次消息”指南来完成从 Firebase 控制台或服务端发送第一条通知。结合仓库代码可以明确示例工程本身不包含任何向设备推送的发送逻辑推送数据面由 FCM 服务端负责。推荐的完整验证路径是本地npm run dev打开页面授权并授权通知权限控制台会打印fcm_token在 Firebase 控制台的 Cloud Messaging 板块新建测试通知将打印出的 Token 填入测试设备标识发送后验证页面处于前台时消息走页面侧消息监听页面关闭或处于后台时由firebase-messaging-sw.js接收。需要特别强调FCM 依赖 Google 提供的推送服务在国内网络环境下可能无法直连 Google 域名示例中的importScriptsCDN 与 Token 获取接口也可能因此不可用——这是接入前必须评估的网络前提并非代码缺陷。小结与可扩展方向该示例用约 60 行核心代码讲清了 Next.js 中 FCM Web 推送的最小可行实现pages/index.js负责客户端触发utils/webPush.js负责权限与 Token 生命周期public/firebase-messaging-sw.js负责后台接收。基于此骨架你可以自然扩展出以下能力在utils/webPush.js增加onMessage前台消息监听与自定义通知渲染在 Service Worker 中实现onBackgroundMessage配合notificationclick处理点击跳转将获取到的 Token 上报到自己的后端用firebase-admin做定向/群发推送将firebase-messaging-sw.js里的 SDK 升级到与页面一致的 v9 以上版本采用模块化导入以减小体积。示例对本地持久化、客户端/Service Worker 双上下文初始化、占位符凭据管理等细节的处理使它可以作为生产项目接入 Web Push 时一个可靠、易读的起点。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考