# @crvouga/mockingbird-service-fcm 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-fcm/

版本：2\.11\.0
npm 元数据更新时间：2026-11-11T02:10:26.113Z
中文译文更新时间：2026-11-11T02:40:16.090Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-fcm
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-fcm/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/fcm#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.3 MB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-10-01T12:43:29.695Z
- 最新版本发布：2026-11-11T02:10:25.489Z
- 近 30 天下载量：15280（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

Firebase Cloud Message HTTP v1的状态仿真器发送了Firebase-admin使用的API:固定工程和注册符,出柜,设备收件箱.

## 安装

```sh
npm install @crvouga/mockingbird-service-fcm
```

也可以使用：`pnpm add @crvouga/mockingbird-service-fcm`、`yarn add @crvouga/mockingbird-service-fcm`、`bun add @crvouga/mockingbird-service-fcm`

## README

# @crvouga/ mockingbird-service-fcm (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

国家模拟器 **Firebase 云传 HTTP v1** 发送 API (`POST /v1/projects/{project_id}/messages:send`),电话 `firebase-admin` 生产。 项目、出入证和登记证都是固定的。 没有FCM沙盒。 这个软件包是 `status: "wip"`。 。 。 .

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/fcm/SUPPORT.md)
-   合同`openapi.yaml`)取自FCM REST参考文献和Firebase-admin 12.7.0 / 13.5.0.

## 安装

```bash
npm install -D @crvouga/mockingbird-service-fcm
```

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 `npx mockingbird-fcm serve`, (中文(简体) ), `createServer` 从 `./server` (节点),或 `createRuntime` 与任何获取服务器.

## 使用量

`firebase-admin` 硬码 `https://fcm.googleapis.com`。将其指向模拟器 `createAdminTransport` (单位:千美元) `https.Agent` 拨打仿真器 `enableLegacyHttpTransport()` 所以,多播送荣誉 该代理. `send` 已经是 HTTP/1.1。 固定项目是 `demo-project`,固定设备符号是 `fixture-device-token`任何持枪者,将被接受,直到你打开 `strict`。 。 。 .

```ts
import { deleteApp, initializeApp } from "firebase-admin/app"
import { getMessaging } from "firebase-admin/messaging"
import { createServer } from "@crvouga/mockingbird-service-fcm/server"
import { createAdminTransport } from "@crvouga/mockingbird-service-fcm/admin"

// Test setup: the emulator, plus a credential and an agent that reach it.
const fcm = await createServer()
const transport = await createAdminTransport({ origin: fcm.url, token: "fixture-token" })

// The application's firebase-admin app. Only its credential and httpAgent change.
const app = initializeApp({
  projectId: "demo-project",
  credential: transport.credential,
  httpAgent: transport.agent,
})
const messaging = getMessaging(app)
messaging.enableLegacyHttpTransport()
const name = await messaging.send({
  token: "fixture-device-token",
  notification: { title: "Hello", body: "World" },
})
// name → "projects/demo-project/messages/<id>"

// Test control: every message the emulator accepted.
const outbox = await (await fetch(`${fcm.url}/__admin/outbox`)).json()
void outbox

await deleteApp(app)
await transport.close()
await fcm.close()
```

### 路线

| 路线 | 行为 |
| --- | --- |
| `POST /v1/projects/{project_id}/messages:send` | 需要熊猫 体质 `{ message, validate_only? }`一. 登记 `token` (专题和条件被拒绝)。 成功是 `{ name: "projects/{project_id}/messages/{id}" }`。错误是一个 Google RPC 信封. `validate_only: true` 验证并返回名称而不存储任何信息. |
| `GET /__admin/health` | 活着,加上 `x-mockingbird` 每个回复都标注在标题上. |

### 管理员

| 路线 | 行为 |
| --- | --- |
| `GET /__admin/outbox` | 接受最古老的讯息 过滤器 : `token`, (中文(简体) ), `platform`, (中文(简体) ), `project`, (中文(简体) ), `since` (划时代), `collapseKey`, (中文(简体) ), `state`。每行都有规范字段和原始字段 `wire` 留言. |
| `POST /__admin/tokens` | 登记册 `{ token, platform?, project?, state?, appId? }`。 。 。 . `tokens: [...]` 注册一批. |
| `POST /__admin/tokens/:token/expire` | 马克过期了 可选 `{ replacement }`。 。 。 . |
| `POST /__admin/tokens/:token/state` | `{ state: active | expired | unregistered | sender_mismatch }`。 。 。 . |
| `GET /__admin/inbox/:token` | 设备收件箱,按交付顺序排列. |
| `POST /__admin/inbox/:token` | `{ action: "ack" }` 放弃最古老的项目. `{ action: "clear" }` 取出空来. |
| `POST /__admin/deliver` | 传达接受的信息。 过期者留在收发箱中作为 `expired`。 。 。 . |
| `POST /__admin/messages/:id/deliver` | 传达一个接受的信息. |
| `POST /__admin/messages/:id/drop` | 马克 `dropped` 不要输入它. |
| `POST /__admin/messages/:id/duplicate` | 再次复制收件箱条目 . |
| `GET /__admin/settings`, (中文(简体) ), `PUT /__admin/settings` | `strict`, (中文(简体) ), `automaticDelivery` (默认的), `collapse` (默认为假), `credentials` (掌声) `{ project, expired? }`, (中文(简体) ), `clockOffsetMs`。 。 。 . |
| `POST /__admin/time` | `{ advanceMs }` 只移动此命名空间的偏移 . |
| `POST /__admin/scripts` | `{ token?, errorCode, count, httpStatus? }`下一个 `count` 向该标志发送(或当 `token` 被省略)返回 Google RPC 错误并存储一无所有。 然后,象征自己的状态适用. |
| `GET /__admin/scripts`, (中文(简体) ), `DELETE /__admin/scripts` | 列表或清晰的脚本. `?token=` 清除一个. |

逻辑消息时间是 `clockOffsetMs` 加上全过程运行时钟. `POST /__admin/clock` 仍然移动每个命名空间。 记录,断层,出箱,收件箱,以及消息代号均为每个取名空间.

### 预设

`POST /__admin/faults {"preset": "<name>"}`每个目标 `SendMessage`数字 :

| 预设 | 效果 |
| --- | --- |
| `invalid_auth` | 401 (中文(简体) ) `UNAUTHENTICATED`,没有存储 |
| `permission_denied` | 403 (韩语) `PERMISSION_DENIED`,没有存储 |
| `invalid_argument` | 400个 `INVALID_ARGUMENT`,没有存储 |
| `unregistered` | 404 (韩语) `NOT_FOUND` + Fcm 错误 `UNREGISTERED`,没有存储 |
| `sender_mismatch` | 403 + Fcm 错误 `SENDER_ID_MISMATCH`,没有存储 |
| `quota_exceeded` | 429个 `RESOURCE_EXHAUSTED`, (中文(简体) ), `Retry-After`, (中文(简体) ), `google.rpc.RetryInfo`fcm 错误 `QUOTA_EXCEEDED` |
| `unavailable` | 503 + Fcm 错误 `UNAVAILABLE` |
| `internal` | 500 + Fcm 错误 `INTERNAL` |
| `slow` | 等待 15s( 消防基地管理员发送超时) |
| `drop` | 接受前退出连接; 发件箱为空 |
| `accepted_then_network_drop` | 保存出盒记录,然后连接下降 |

### 命名空间

`x-mockingbird-namespace`页:1 `/__admin/ns/<name>/` 前缀,或 `PUT /__admin/credentials` (接发者-取名空间. 列于 `settings.credentials` 仅授权该项目. `strict: true` 拒绝未列入清单的持有人。 网友:无. 设备收件箱是一个测试控制,而不是回调.

### SDK 错误代码

火炮基地地图 `error.details[].errorCode` 何时 `@type` 实值 `type.googleapis.com/google.firebase.fcm.v1.FcmError`,否则 `error.status`. 两种绘图方法与对错误代码名称的天真解读不同,模拟器遵循火地-admin 12.7.0和13.5.0:

-   A JSON 401 具有地位 `UNAUTHENTICATED` 没有 Fcm 细节变成 `messaging/third-party-auth-error`。 。 。 . `messaging/authentication-error` sDK对非JSON 401的用法.
-   Fcm 错误 `DEADLINE_EXCEEDED` sDK报告不在邮件地图中 `messaging/unknown-error`。 。 。 . `UNAVAILABLE` 实值 `messaging/server-unavailable`。 。 。 .

`INVALID_ARGUMENT`, (中文(简体) ), `SENDER_ID_MISMATCH`, (中文(简体) ), `QUOTA_EXCEEDED`, (中文(简体) ), `UNAVAILABLE`,以及 `INTERNAL` 地图到 `messaging/invalid-argument`, (中文(简体) ), `messaging/mismatched-credential`, (中文(简体) ), `messaging/message-rate-exceeded`, (中文(简体) ), `messaging/server-unavailable`,以及 `messaging/internal-error`二. 现况 `PERMISSION_DENIED` (另一个项目的持有人)也是 `messaging/mismatched-credential`。 。 。 .

### 故意不模拟

-   Firebase Auth, Firestore, 实时数据库,主机,远程配置,分析,以及客户端安装API.
-   主题和条件发送,以及主题订阅管理.
-   APN和Android运输,真设备,应用回调,通知渲染,徽章,和声.
-   生产配额和Google未公布的重试时间表. 行政主管SDK自己的重试(503, `ECONNRESET`, (中文(简体) ), `ETIMEDOUT`)是留给SDK的.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `FcmAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `logicalNow()`, (中文(简体) ), `outbox(query)`, (中文(简体) ), `inbox(token)`, (中文(简体) ), `registerToken`, (中文(简体) ), `setTokenState`, (中文(简体) ), `ackInbox`, (中文(简体) ), `deliverPending`, (中文(简体) ), `dropMessage`, (中文(简体) ), `duplicateMessage`, (中文(简体) ), `putScript`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `settings`。 。 。 . |
| `createRuntime` | 函数 | 模拟器加 `/__admin/health`, (中文(简体) ), `/__admin/*`名称空间 时钟 预设 日记 选项 : `sqlite`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`, (中文(简体) ), `settings`。 。 。 . |
| `FCM_PRESETS` | 对象 | 命名了断层预设 . |
| `FCM_NAMESPACE` | 字符串 | 服务名称, `"fcm"`。 。 。 . |
| `FCM_FIXTURE_PROJECT` | 字符串 | 种子项目编号, `"demo-project"`。 。 。 . |
| `FCM_FIXTURE_TOKEN` | 字符串 | 种子安卓注册证, `"fixture-device-token"`。 。 。 . |
| `FCM_FIXTURE_BEARER` | 字符串 | 游乐场派来的人, `"fixture-token"`. 何时接受 `strict` 关闭. |
| `fcmCredential` | 函数 | `(accessToken?)` → `{ getAccessToken }` 页:1 `initializeApp({ credential })`。 。 。 . |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | OpenAPI合同及其操作代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`. CLI 旗帜 `--strict`. Port 8826 (英语). |
| `createAdminTransport` (单位:千美元)`./admin`(中文(简体) ) | 节点 | `{ origin, token? }` → `{ credential, agent, port, close }`。 。 。 . `agent` 是一个 `https.Agent` 瞄准模拟器. |

部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-fcm 是什么？

Firebase Cloud Message HTTP v1的状态仿真器发送了Firebase-admin使用的API:固定工程和注册符,出柜,设备收件箱\.

### 如何安装 @crvouga/mockingbird-service-fcm？

在项目目录运行 npm install @crvouga/mockingbird-service-fcm，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-fcm，可以用 npx mockingbird-fcm 直接运行。

### @crvouga/mockingbird-service-fcm 支持 TypeScript 吗？

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

### @crvouga/mockingbird-service-fcm 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @crvouga/mockingbird-service-fcm 可以商用吗？

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

### @crvouga/mockingbird-service-fcm 的下载量有多少？

根据 npm 官方下载统计，@crvouga/mockingbird-service-fcm 在 2026/10/11 – 2026/11/09 这 30 天内被下载 15,280 次，日均约 509 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crvouga/mockingbird-service-fcm 还在维护吗？

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