更新记录

1.0.0（2026-03-26） 下载此版本

初版，支持 FCM 初始化、Token 获取、消息缓存拉取、Android13 通知权限申请

平台兼容性

Lak-FCM 使用说明

Lak-FCM 是一个 uni-app Android 原生插件，用于接入 Firebase Cloud Messaging（FCM），不依赖 uni-push。

1. 支持平台

• uni-app（app-vue / app-nvue）
• Android 5.0+（API 21+）
• iOS：暂不支持（需单独实现 APNs + FCM iOS）

2. 前置准备

1. 在 Firebase 控制台创建 Android 应用（包名需与打包包名一致）
2. 获取 google-services.json
3. 在云打包/插件配置中按平台要求提供该文件
4. Android 13+ 需要通知权限（POST_NOTIFICATIONS）

3. 安装插件

1. 插件市场安装 Lak-FCM
2. 项目中通过 uni.requireNativePlugin('Lak-FCM') 调用
3. 推荐直接使用项目封装：@/common/fcm.js

4. API 列表

init({ autoRequestPermission })

初始化 FCM。

• 入参：
  • autoRequestPermission（boolean，默认 true）：是否自动请求 Android 13+ 通知权限
• 返回：
  • { code, message, token }

getToken()

获取 FCM Token（优先返回本地缓存）。

• 返回：
  • { code, message, token, fromCache }

deleteToken()

删除当前 FCM Token。

• 返回：
  • { code, message }

pullMessages({ clear })

拉取插件缓存的消息（来源：onMessageReceived）。

• 入参：
  • clear（boolean，默认 true）：拉取后是否清空缓存
• 返回：
  • { code, message, messages, clear }

requestNotificationPermission()

手动请求 Android 13+ 通知权限。

• 返回：
  • { code, message, granted }

5. JS 调用示例

import {
  fcmInit,
  fcmGetToken,
  fcmPullMessages,
  fcmRequestNotificationPermission
} from '@/common/fcm.js'

async function startFCM() {
  await fcmRequestNotificationPermission()

  const initRes = await fcmInit(true)
  console.log('initRes', initRes)

  const tokenRes = await fcmGetToken()
  console.log('token', tokenRes.token)
  // TODO: 上报 token 到业务后端

  const msgRes = await fcmPullMessages(true)
  console.log('messages', msgRes.messages || [])
}

6. 在线/离线消息建议

• onLaunch：初始化并拉取一次离线消息
• onShow：立即拉一次 + 启动轮询拉取（如 3 秒一次）
• onHide：停止轮询

建议将消息统一抛到业务层：

uni.$emit('fcm-message', item)

页面监听：

uni.$on('fcm-message', (msg) => {
  // 业务处理
})

7. 常见问题

7.1 拿不到 Token

• 检查 google-services.json 是否匹配包名
• 检查设备网络与 Google 服务可用性
• 确认 Firebase 项目配置完整

7.2 收不到消息

• 确认服务端推送目标 token 正确
• 前后台消息类型（notification/data）行为不同
• Android 13+ 是否授予通知权限

7.3 code = -1 插件不可用

• 检查插件 ID 是否与调用一致：Lak-FCM
• 检查插件是否成功安装到项目
• 重新云打包并安装最新包

8. 隐私与合规

• 插件会读取并返回 FCM Token
• 插件会缓存收到的消息内容供 JS 层拉取
• 生产环境请勿打印完整 Token / 敏感消息正文