# @12-apps/realtime 中文文档

规范地址：https://npmcn.com/package/%4012-apps/realtime/

版本：2\.10\.0
npm 元数据更新时间：2026-11-05T04:06:12.946Z
中文译文更新时间：2026-11-05T19:53:11.963Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4012-apps/realtime
原文对照：https://npmcn.com/package/%4012-apps/realtime/?lang=original
项目主页：https://github.com/12-apps/shared-packages#readme
源码仓库：https://github.com/12-apps/shared-packages

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

- 包体积（解压后）：404 kB，62 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：1 个
- peer 依赖：ws \>=8\.0\.0，tsx \>=4\.0\.0，hono \>=4\.0\.0，react \>=19\.0\.0，react-dom \>=19\.0\.0，@12-apps/wiring \>=1\.3\.0
- 首次发布：2026-08-05T02:17:39.307Z
- 最新版本发布：2026-11-05T04:06:12.544Z
- 近 30 天下载量：32930（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

通用的,便携式的实时Event系统。 无框架核心(类型主题/活动信封和一个可互换驱动程序端口后面的发布/订阅总线:Redis pub/sub跨进程,内置进程内用于dev和测试),主机挂后端表面(./ser)

## 安装

```sh
npm install @12-apps/realtime
```

也可以使用：`pnpm add @12-apps/realtime`、`yarn add @12-apps/realtime`、`bun add @12-apps/realtime`

## README

# @ 12- apps/ 实时

便携式实时 **事件系统**: 总线、 授权和 流出它,一个可运行的 WebSocket网关,一个交易出柜,浏览器客户端,以及 门,使可分解域不被航运沉默.

2家工厂,每个工厂1个配置对象 [采用.md](https://npmcn.com/package/%4012-apps/realtime/ADOPTING.md)。 。 。 .

```ts
// backend
const events = eventsRouter({ surfaces, outbox: { db: () => prisma } });
app.route("/api", events.router);
await events.start();

// frontend
const web = createWebEvents({ apiBase: "/api" });
const { status } = web.useTopics({ topics: ["kitchen"], onMessage: invalidate });
useQuery({ /* … */ refetchInterval: reconcileRefetchInterval(status, POLL_MS, RECONCILE_MS) });
```

| 子路径 | 这是什么 |
| --- | --- |
| `.` | 无框架总线:主题, `publishRealtimeEvent`, (中文(简体) ), `subscribeRealtime`,驱动端口,内置驱动程序 |
| `./redis` | 跨进程驱动程序, 隐藏在自己的子路径后, 所以一个发射站点永远不会拖动 `ioredis` 装入捆绑 |
| `./ticket` | 连接车票:薄荷、验证、单用警卫 |
| `./server` | `createApiEvents` - 专题登记、授权接合、SSE运输、连接盖、发包箱 |
| `./hono` | `eventsRouter` 单调挂起(`hono` 是可选对等点) |
| `./gateway` | `startRealtimeGateway`外加一个 `realtime-gateway` 宾 (`ws` 是可选对等点) |
| `./react` | `createWebEvents` ——客户端,重联政策,ws-sse降级,活人表,钩子 |
| `./node` | 同一客户端的运行时间没有 `EventSource` 事件流 `WireSource` 结束 `fetch`,用于桌面代理、工人或CLI |
| `./worker` | 共享工人体,为希望一个人连接的宿主 |
| `./parity` | 出版商-均等门: 库 + CLI |
| `prisma/` | 发件箱模式 + 其迁移, 复制到主机的 schema 文件夹 |

## 三个规则 其他一切从

-   **出版从不扔.** 实时是消费者投票的暂时优化 倒行逆施,因此一出公交车停用会降解为"下个民意调查所见"——永远不会变成失败的突变.
-   **送货最好** 没有重播。 每次活动都是对READ的提示 数据库保持真相的来源 民意调查是永久的,只有实时 放松点. `data` 载有识别器,从未说明... 这里的有效载荷是第二, 未加保管的核准决定副本.
-   **网关没有执行授权 .** API 表面由主机自己的规则决定 并签名 RESOLVED 主题名称 成短寿命,单一使用票。 一个话题是 从未被移交过从未被订阅过, 因此网关错误可以打破套接字但不能 泄露另一个房客的事件.

**接通后出现.** 一个地表 `authorize` 可能命名存在密钥; 进程 持有连接宣布 `held` 当它打开时( 从服务器更新) 和 `released` 当它关闭,和API's `presence.onChange` 听到每个持有者——没有心跳 任何浏览器中的民意调查 。 见Adopting.md,"Presence".

其保证是: 完全的坚持, **至少与一等消费者一起出版**,没有总订单. 见Adopting.md——它并不是一成不变的,也不是假装的.

## 常见问题

### @12-apps/realtime 是什么？

通用的,便携式的实时Event系统。 无框架核心\(类型主题/活动信封和一个可互换驱动程序端口后面的发布/订阅总线:Redis pub/sub跨进程,内置进程内用于dev和测试\),主机挂后端表面\(\./ser\)

### 如何安装 @12-apps/realtime？

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

### @12-apps/realtime 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/12-apps\_\_realtime 是否存在。

### @12-apps/realtime 支持 ESM 还是 CommonJS？

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

### @12-apps/realtime 需要什么版本的 Node\.js？

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

### @12-apps/realtime 可以商用吗？

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

### @12-apps/realtime 的下载量有多少？

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

### @12-apps/realtime 还在维护吗？

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