# @adonisjs/transmit 中文文档

规范地址：https://npmcn.com/package/%40adonisjs/transmit/

版本：3\.0\.2
npm 元数据更新时间：2026-08-25T19:19:55.233Z
中文译文更新时间：2026-11-05T18:12:16.115Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adonisjs/transmit
原文对照：https://npmcn.com/package/%40adonisjs/transmit/?lang=original
项目主页：https://github.com/adonisjs/transmit#readme
源码仓库：https://github.com/adonisjs/transmit

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

- 包体积（解压后）：52.2 kB，57 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.11\.1
- 运行依赖：1 个
- peer 依赖：@adonisjs/core ^7\.0\.0-next
- 首次发布：2023-07-07T19:44:21.244Z
- 最新版本发布：2026-08-25T19:19:54.900Z
- 近 30 天下载量：99018（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 4 个）

## 中文简介

一个Server-Sent-Event模块将实时能力带到了AdonisJS.

## 安装

```sh
npm install @adonisjs/transmit
```

也可以使用：`pnpm add @adonisjs/transmit`、`yarn add @adonisjs/transmit`、`bun add @adonisjs/transmit`

## README

# 阿多尼斯JS 传送

AdonisJS的本地服务器-Sent-Event(SSE)模块.

  

[![typescript-image](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/) [![gh-workflow-image](https://img.shields.io/github/actions/workflow/status/adonisjs/transmit/checks.yml?branch=3.x&style=for-the-badge)](https://github.com/adonisjs/transmit/actions/workflows/checks.yml "GitHub action") [![npm-image](https://img.shields.io/npm/v/@adonisjs/transmit.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@adonisjs/transmit) [![npm-download-image](https://img.shields.io/npm/dm/@adonisjs/transmit?style=for-the-badge)](https://www.npmjs.com/package/@adonisjs/transmit) [![license-image](https://img.shields.io/npm/l/@rlanz/bus?color=blueviolet&style=for-the-badge)](https://npmcn.com/package/%40adonisjs/transmit/LICENSE.md)

### [使用量](https://npmcn.com/package/%40adonisjs/transmit/#readme-installation) | [检查 AdonisJS](https://adonisjs.com/)

  

* * *

AdonisJS Transmit是AdonisJS的本地服务器-Sent-Event (SSE)模块. 它为发送事件给客户端提供了简单的API. 它还支持 [重写](https://redis.io/) 作为向多个服务器或实例广播事件的传输层.

在使用这个模块之前,你应该先知道一些事情.

👉 **单向通信:** 数据传输只发生在服务器到客户端之间,而不是相反.  
👉 **文本数据 仅限:** SSE只支持文本数据的传输,不能发送二进制数据.  
👉 **HTTP 协议 :** 使用的基本协议是常规的HTTP,而不是任何特殊或专有的协议.  

## 目录

-   [安装](https://npmcn.com/package/%40adonisjs/transmit/#readme-installation)
-   [使用量](https://npmcn.com/package/%40adonisjs/transmit/#readme-usage)
-   [频道](https://npmcn.com/package/%40adonisjs/transmit/#readme-channels)
    -   [频道名称](https://npmcn.com/package/%40adonisjs/transmit/#readme-channel-names)
    -   [频道授权](https://npmcn.com/package/%40adonisjs/transmit/#readme-channel-authorization)
-   [客户端](https://npmcn.com/package/%40adonisjs/transmit/#readme-client)
-   [同步中](https://npmcn.com/package/%40adonisjs/transmit/#readme-syncing)
-   [Ing](https://npmcn.com/package/%40adonisjs/transmit/#readme-ping)
-   [活动](https://npmcn.com/package/%40adonisjs/transmit/#readme-events)
-   [测试](https://npmcn.com/package/%40adonisjs/transmit/#readme-testing)
-   [避免GZIP干扰](https://npmcn.com/package/%40adonisjs/transmit/#readme-avoiding-gzip-interference)

## 安装

从 npm 登记册中安装软件包如下:

```sh
node ace add @adonisjs/transmit
```

## 使用量

模块显示 `transmit` 实例,用于向客户端发送事件.

```ts
import transmit from '@adonisjs/transmit/services/main'

// Anywhere in your code
transmit.broadcast('channelName', { username: 'lanz' })
```

## 频道

频道是组织事件的一种方式. 例如,您可以有一个频道用于 `users` 和另一个用于 `posts`。客户端可以订阅一个或多个频道接收事件.

### 频道名称

频道名称必须是一个字符串,除此之外不得包含任何特殊字符 `/`。以下是有效的频道名称.

```ts
transmit.broadcast('users', { username: 'lanz' })
transmit.broadcast('users/1', { username: 'lanz' })
transmit.broadcast('users/1/posts', { username: 'lanz' })
```

### 频道授权

您可以将频道标为私人频道,然后授权客户端订阅. 授权使用回调函数进行.

```ts
// start/transmit.ts

import type { HttpContext } from '@adonisjs/core/http'

transmit.authorize<{ id: string }>('users/:id', (ctx: HttpContext, { id }) => {
  return ctx.auth.user?.id === +id
})
```

> \[注\] 别忘了加上你 `start/transmit.ts` 文件在 `preloads` 数组 `adonisrc.ts` 文档.

当客户端试图订阅一个私人频道时,会以频道参数和HTTP上下文来引用回调函数. 回调函数必须返回布尔值以允许或不允许订阅 .

这个 `ctx` 当订阅请求通过您认证的中间软件时, 才会带一个认证的用户 。 默认情况下, 用于订阅和取消订阅的路由( X)`__transmit/subscribe` 财务报告和审定财务报表 `__transmit/unsubscribe`)是公开的,所以 `ctx.auth.user` 实值 `undefined`启用 `transmit.registerRoutes` 保护他们:

```ts
// start/routes.ts

import transmit from '@adonisjs/transmit/services/main'
import { middleware } from '#start/kernel'

transmit.registerRoutes((route) => {
  // Authenticate the client before it can subscribe to a channel
  if (route.getPattern() === '__transmit/subscribe') {
    route.middleware(middleware.auth())
    return
  }
})
```

> \[注\] 一旦订阅路线被认证, `ctx.auth.user` 在您内部 `authorize` 调用,允许您将私有频道范围限制到当前用户.

## 客户端

这个 `@adonisjs/transmit-client` 软件包允许您连接到服务器,订阅频道,并对收到的信息作出反应.

```sh
npm i @adonisjs/transmit-client
```

通过指向您的服务器创建客户端 。 当您的订阅路由被认证时( 请参见 [频道授权](https://npmcn.com/package/%40adonisjs/transmit/#readme-channel-authorization)),使用 `beforeSubscribe` 勾勾在每次订阅请求中附上您的证书 。 钩子接收出局 `Request`,可以直接改变其标题.

```ts
import { Transmit } from '@adonisjs/transmit-client'

export const transmit = new Transmit({
  baseUrl: window.location.origin,
  beforeSubscribe: (request) => {
    request.headers.set('Authorization', `Bearer ${getToken()}`)
  },
})
```

然后订阅频道并收听消息:

```ts
const subscription = transmit.subscription('users/1')
await subscription.create()

subscription.onMessage((message) => {
  console.log(message)
})

// Stop receiving messages
await subscription.delete()
```

> \[注\] 如果您也保护未订阅的路由, 请使用匹配 `beforeUnsubscribe` 要认证的钩 `__transmit/unsubscribe` 请求同样的方式.

# 同步中

传输支持跨多个服务器同步事件或使用传输层的事件. 您可以通过改变配置和引用驱动程序来启用同步( 目前只有 Redis 可用) .

```ts
// config/transmit.ts
import env from '#start/env'
import { defineConfig } from '@adonisjs/transmit'
import { redis } from '@adonisjs/transmit/transports'

export default defineConfig({
  transport: {
    driver: redis({
      host: env.get('REDIS_HOST'),
      port: env.get('REDIS_PORT'),
      password: env.get('REDIS_PASSWORD'),
    }),
  },
})
```

> \[注\] 确保有 `ioredis` 使用时安装 `redis` 驾驶员.

# Ing

传输支持拨打客户端以保持连接. 您可以通过改变配置来启用 ping.

```ts
// config/transmit.ts
import { defineConfig } from '@adonisjs/transmit'
import { redis } from '@adonisjs/transmit/transports'

export default defineConfig({
  pingInterval: '1m',
})
```

# 活动

传输用途 [娱乐](https://github.com/sindresorhus/emittery) 释放任何生命周期事件。 您可以使用 `on` 方法.

```ts
transmit.on('broadcast', ({ channel, payload }) => {
  logger.debug('TRANSMIT broadcasted')
  logger.debug(`─ channel: ${channel}`)
  logger.debug(`─ payload: ${JSON.stringify(payload)}`)
})

transmit.on('connect', ({ uid }) => {
  logger.debug('TRANSMIT connected')
  logger.debug(`─ uid: ${uid}`)
})

transmit.on('disconnect', ({ uid }) => {
  logger.debug('TRANSMIT disconnected')
  logger.debug(`─ uid: ${uid}`)
})

transmit.on('subscribe', ({ channel, uid }) => {
  logger.debug('TRANSMIT subscribed')
  logger.debug(`─ channel: ${channel}`)
  logger.debug(`─ uid: ${uid}`)
})

transmit.on('unsubscribe', ({ channel, uid }) => {
  logger.debug('TRANSMIT unsubscribed')
  logger.debug(`─ channel: ${channel}`)
  logger.debug(`─ uid: ${uid}`)
})
```

这个 `connect` 财务报告和审定财务报表 `disconnect` 事件暴露了 `uid` 客户。 与 [频道授权](https://npmcn.com/package/%40adonisjs/transmit/#readme-channel-authorization)您可以绘制地图 `uid` 到经认证的用户,以跟踪当前连接的人.

# 测试

因为 `transmit.on` 返回一个停止监听的函数,您可以在击中您的端点时收集所发射的广播,并对此进行断言。 以下示例使用了 [日本兵团](https://japa.dev/) 与 `@japa/api-client` 插件 :

```ts
import transmit from '@adonisjs/transmit/services/main'
import { test } from '@japa/runner'

test.group('Posts', () => {
  test('it broadcasts the created post', async ({ client, assert }) => {
    const broadcasts: { channel: string; payload: unknown }[] = []
    const stopListening = transmit.on('broadcast', (event) => broadcasts.push(event))

    const response = await client.post('/posts').loginAs(user)

    stopListening()

    assert.equal(response.status(), 201)
    assert.lengthOf(broadcasts, 1)
    assert.equal(broadcasts[0].channel, `users/${user.id}`)
  })

  test('it rejects an unauthenticated subscription', async ({ client, assert }) => {
    const response = await client.post('/__transmit/subscribe').json({ channel: 'users/1' })

    assert.equal(response.status(), 401)
  })
})
```

# 避免GZIP干扰

部署使用的程序时 `@adonisjs/transmit`,必须确保GZip压缩不会干扰 `text/event-stream` server-Sent Events(SSE)使用的内容类型. 压缩应用到 `text/event-stream` 可以引起连接问题,导致频繁断开或SSE故障.

如果您的部署使用了反向代理( 如 Traefik 或 Nginx) 或其他应用 GZip 的中间软件, 请确保 压缩被禁用 `text/event-stream` 内容类型.

## 特拉菲克的示例配置

```plaintext
traefik.http.middlewares.gzip.compress=true
traefik.http.middlewares.gzip.compress.excludedcontenttypes=text/event-stream
traefik.http.routers.my-router.middlewares=gzip
```

## 常见问题

### @adonisjs/transmit 是什么？

一个Server-Sent-Event模块将实时能力带到了AdonisJS\.

### 如何安装 @adonisjs/transmit？

在项目目录运行 npm install @adonisjs/transmit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@adonisjs/core（^7\.0\.0-next）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @adonisjs/transmit 支持 TypeScript 吗？

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

### @adonisjs/transmit 支持 ESM 还是 CommonJS？

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

### @adonisjs/transmit 需要什么版本的 Node\.js？

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

### @adonisjs/transmit 可以商用吗？

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

### @adonisjs/transmit 的下载量有多少？

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

### @adonisjs/transmit 还在维护吗？

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