# @sadikkhan02/adapter-fcm 中文文档

规范地址：https://npmcn.com/package/%40sadikkhan02/adapter-fcm/

版本：1\.0\.0
npm 元数据更新时间：2026-11-02T08:20:35.907Z
中文译文更新时间：2026-11-02T10:20:53.957Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40sadikkhan02/adapter-fcm
原文对照：https://npmcn.com/package/%40sadikkhan02/adapter-fcm/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：79.9 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- peer 依赖：firebase-admin \>=11\.0\.0，@sadikkhan02/notifykit ^1\.0\.0
- 首次发布：2026-11-02T08:19:39.935Z
- 最新版本发布：2026-11-02T08:20:35.747Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于NotifyKit的Firebase Cloud Messaging （FCM）推送通知提供程序适配器

## 安装

```sh
npm install @sadikkhan02/adapter-fcm
```

也可以使用：`pnpm add @sadikkhan02/adapter-fcm`、`yarn add @sadikkhan02/adapter-fcm`、`bun add @sadikkhan02/adapter-fcm`

## README

# `@sadikkhan02/adapter-fcm`

> 移动和Web推送通知适配器的NotifyKit使用Firebase云消息（FCM）。

这个包通过谷歌Firebase Cloud Messaging v1 API在Android、iOS（通过FCM的apn）和Web浏览器上提供推送通知。它符合 `PushProvider` 契约，对非字符串数据有效负载进行字符串化，并优雅地处理令牌无效。

* * *

## 安装

```bash
npm install @sadikkhan02/notifykit @sadikkhan02/adapter-fcm firebase-admin
```

> **注意：** `firebase-admin` 被声明为外部对等依赖，以允许消费者控制SDK版本绑定、谷歌云环境认证和Firebase应用程序池。

* * *

## 配置和凭据

FCM需要谷歌的云服务帐户凭据 **Firebase云消息传递API管理** 的角色。

### 环境变量

| 变量 | 描述 |
| :-- | :-- |
| `FCM_SERVICE_ACCOUNT_JSON` | 原始JSON字符串或Firebase服务帐户密钥的文件路径 |
| `GOOGLE_APPLICATION_CREDENTIALS` | 标准谷歌云SDK凭据路径回退 |
| `FCM_PROJECT_ID` | 可选显式谷歌云项目ID |

### 优先级顺序

适配器按以下顺序解析服务帐户凭据：

1.  直接 `serviceAccount` 参数 `new FcmPushProvider({ serviceAccount: ... })` （对象、JSON字符串或文件路径）
2.  `process.env.FCM_SERVICE_ACCOUNT_JSON`
3.  `process.env.GOOGLE_APPLICATION_CREDENTIALS`
4.  预重火力点 `app` 或者 `messaging` 客户端注入期权

* * *

## 使用

```typescript
import { createNotifier } from '@sadikkhan02/notifykit';
import { FcmPushProvider } from '@sadikkhan02/adapter-fcm';

const pushProvider = new FcmPushProvider({
  // Can be an object, JSON string, or file path:
  serviceAccount: process.env.FCM_SERVICE_ACCOUNT_JSON,
});

const notifier = createNotifier({
  providers: {
    push: {
      type: 'fcm',
      adapter: pushProvider,
    },
  },
});

// Register push notification template
notifier.registerTemplate('new-message', '{{sender}} sent you a new message: {{preview}}');

// Enqueue push notification (returns immediately with jobId)
const { jobId } = await notifier.notify({
  to: { pushToken: 'fcm_device_registration_token_xyz...' },
  channels: ['push'],
  template: 'new-message',
  data: {
    sender: 'Sarah',
    preview: 'Hey, are you free for a call?',
    // Data values are automatically stringified for FCM compliance
    conversationId: 'conv_123',
  },
});

// Start processing push queue
notifier.startWorker({ channels: ['push'], concurrency: 20 });
```

* * *

## 错误分类和DLQ路由

FCM错误代码被清晰地分类为瞬时网络/服务器故障和永久令牌失效：

| FCM /谷歌错误码 | 描述 | `retryable` | BullMQ行动 |
| :-- | :-- | :-- | :-- |
| `messaging/server-unavailable` | 谷歌FCM后端过载 | `true` | 以指数回退重试 |
| `messaging/internal-error` | 短暂的内部Firebase错误 | `true` | 以指数回退重试 |
| `messaging/quota-exceeded` | 项目发送速率受限 | `true` | 以指数回退重试 |
| `messaging/unknown-error` | 未知的网络/网关故障 | `true` | 以指数回退重试 |
| `messaging/registration-token-not-registered` | 设备卸载的应用/令牌过期 | `false` | 直接路由到DLQ（不重试） |
| `messaging/invalid-registration-token` | 格式错误或损坏的令牌字符串 | `false` | 直接路由到DLQ（不重试） |
| `messaging/mismatched-credential` | 令牌属于不同的发送方ID | `false` | 直接路由到DLQ（不重试） |
| `messaging/authentication-error` | 无效的服务帐户或过期的密钥 | `false` | 直接路由到DLQ（不重试） |

### 自动私钥清理

所有错误日志和提供程序结果都会自动剥离私钥(`BEGIN PRIVATE KEY`)、不记名令牌和客户端秘密。

* * *

## 许可证

麻省理工学院

## 常见问题

### @sadikkhan02/adapter-fcm 是什么？

用于NotifyKit的Firebase Cloud Messaging （FCM）推送通知提供程序适配器

### 如何安装 @sadikkhan02/adapter-fcm？

在项目目录运行 npm install @sadikkhan02/adapter-fcm，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：firebase-admin（\>=11\.0\.0）、@sadikkhan02/notifykit（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @sadikkhan02/adapter-fcm 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @sadikkhan02/adapter-fcm 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @sadikkhan02/adapter-fcm 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @sadikkhan02/adapter-fcm 可以商用吗？

@sadikkhan02/adapter-fcm 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @sadikkhan02/adapter-fcm 还在维护吗？

最新版本 1\.0\.0 发布于 2026/11/02（1 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。