# @ably/laravel-echo 中文文档

规范地址：https://npmcn.com/package/%40ably/laravel-echo/

版本：1\.0\.6
npm 元数据更新时间：2026-10-14T11:06:13.521Z
中文译文更新时间：2026-11-05T20:19:00.528Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ably/laravel-echo
原文对照：https://npmcn.com/package/%40ably/laravel-echo/?lang=original
项目主页：https://github.com/ably-forks/laravel-echo
源码仓库：https://github.com/ably-forks/laravel-echo

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

- 包体积（解压后）：439 kB，107 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10
- 运行依赖：0 个
- peer 依赖：ably ^1\.2
- 首次发布：2022-10-24T16:38:52.800Z
- 最新版本发布：2024-09-26T12:43:30.244Z
- 近 30 天下载量：29389（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 0 个）

## 中文简介

Laravel Echo 图书馆,用于美丽的 Ably 集成

## 安装

```sh
npm install @ably/laravel-echo
```

也可以使用：`pnpm add @ably/laravel-echo`、`yarn add @ably/laravel-echo`、`bun add @ably/laravel-echo`

## README

## 导言

此寄存器为 [https://github.com/laravel/echo (英语)](https://github.com/laravel/echo)。它坚持从基础存储库中获取公共界面方法。 它将定期与基站寄存器同步,以确保所有代码都是最新的. 增加了针对具体情况的执行,以支持本地 [强能js](https://github.com/ably/ably-js)。 。 。 .

## 安装

安装 `@ably/laravel-echo` 和最新版本的 `ably` 使用 npm (可插式 lib) .

```bash
npm install @ably/laravel-echo ably@1.x
```

Echo 安装后, 您准备在您的应用程序的 JavaScript 中创建新的 Echo 实例 。 做这个的好地方就在下面 `resources/js/bootstrap.js` 包含在 Laravel 框架中的文件。 默认情况下, Echo 配置已经包含在此文件中; 但是, 默认配置在 `bootstrap.js` 文件用于 Pusher 。 您可以将配置复制到下面, 将配置切换到 Ably .

```js
import Echo from '@ably/laravel-echo';
import * as Ably from 'ably';

window.Ably = Ably; // make globally accessible to Echo
window.Echo = new Echo({
    broadcaster: 'ably',
});

window.Echo.connector.ably.connection.on(stateChange => {
    if (stateChange.current === 'connected') {
        console.log('connected to ably server');
    }
});
```

-   看看这个 [laravel 广播认证端点](https://laravel.com/docs/broadcasting#customizing-the-authorization-endpoint) 用于自定义认证端点.

```
    broadcaster: 'ably',
    authEndpoint: '/broadcasting/auth' // relative or absolute url to laravel-server
```

-   你可以设置额外的能力J [js-客户选项](https://ably.com/docs/api/realtime-sdk?lang=javascript#client-options) 创建时 `Echo` 举个例子 其中一些是... ...... .....

```
    broadcaster: 'ably',
    // ably specific client-options
    echoMessages: true, // self-echo for published message is set to false internally.
    queueMessages: true, // default: true, maintains queue for messages to be sent.
    disconnectedRetryTimeout: 15000, // reconnect after 15 seconds when client goes disconnected state
    suspendedRetryTimeout: 30000, // reconnect after 30 seconds when client goes suspended state
```

-   [认证特定客户端选项](https://sdk.ably.com/builds/ably/specification/main/features/#AO1) 不应该使用,因为拉拉维尔 `authEndpoint` 已经负责符号认证,不需要外部认证机制.

一旦您根据需要对 Echo 配置进行了解析和调整,您就可以编译您的应用程序的资产 :

```shell
npm run dev
```

-   如果您在客户端使用 SPA , 在用户登录时, 新的客户端ID 会被指定到符上 。 因此,下一个通道附件的连接进入失败状态 。 我们已经解决这个问题。 现在,它立即重新连接, 重新连接所有现有的频道。 见 [修复客户端ID不匹配](https://github.com/ably-forks/laravel-echo/pull/38) 更多细节。 在用户登录时,连接+通道会进入失败状态,不再重新连接. 因此,您需要在用户登录后创建一个新的 Echo 实例 .

## 使用自定义执行与 laravel sanctum/ 支持通道认证合作

-   有明确一节说明 [授权私人/新闻广播频道](https://laravel.com/docs/sanctum#authorizing-private-broadcast-channels)。 。 。 .
-   这相当于提供 `requestTokenFn` 在创建 Echo 实例时作为参数

```js
    echo = new Echo({
            broadcaster: 'ably',
            useTls: true,
            requestTokenFn: async (channelName: string, existingToken: string) => {
                let postData = { channel_name: channelName, token: existingToken };
                const res = await axios.post("/api/broadcasting/auth", postData);
                return res.data;
            },
    });
```

-   注:不为以上代码添加尝试/捕获语句,因为例外情况正在内部处理.

## 观察频道消息的精通dev-console和离开频道

-   您可以使用

```
//public channel
let echoPublicChannel = Echo.channel('channel1');
let ablyPublicChannelName = echoPublicChannel.name;
console.log(ablyPublicChannelName); // public:channel1

// private channel
let echoPrivateChannel = Echo.private('channel2');
let ablyPrivateChannelName = echoPrivateChannel.name;
console.log(ablyPrivateChannelName); // private:channel2

// presence channel
let echoPresenceChannel = Echo.join('channel3');
let ablyPresenceChannelName = echoPresenceChannel.name;
console.log(ablyPresenceChannelName); // presence:channel3
```

-   使用同一频道名称 [在 dev 控制台上观察频道消息](https://ably.com/docs/tools#developer-console)。 。 。 .
-   离开频道时使用相同的频道名称

```
Echo.leaveChannel(echoPublicChannel.name);
Echo.leaveChannel(echoPrivateChannel.name);
Echo.leaveChannel(echoPresenceChannel.name);
```

## 成功/未能确认低语

-   您可以通过传递额外的回调参数来获取对在私人/ 存在频道发送的低语/ 客户端- 事件的确认 .
-   额外调用是接收 `err` 表示成功/失败的对象.

```
        echoPrivateChannel.subscribed(() => {
                echoPrivateChannel.whisper('msg', 'Hello there jonny!', (err) => {
                    if(err) {
                        console.log('whisper failed with error ' + err);
                    } else {
                        console.log('whisper succeeded');
                    }
                });
            });
```

## 正式文件

-   Echo 的更多文档可见于 [拉拉维尔网站](https://laravel.com/docs/broadcasting)。 。 。 .

## 捐款

-   确保所有公共互动方法 `Echo` 财务报告和审定财务报表 `Channel` 无论内部实施与否,物体均保持不变.
-   遵循以下步骤修改代码.

1.  叉来.
2.  创建您的特性分支( E)`git checkout -b my-new-feature`) (中文(简体) ).
3.  提交更改( E)`git commit -am 'Add some feature'`) (中文(简体) ).
4.  确保您添加了合适的测试, 测试套件正在通过( 运行) `vendor/bin/phpunit`(中文(简体) )
5.  推向分行(`git push origin my-new-feature`) (中文(简体) ).
6.  创建新拉请求 .

## 释放进程

此库使用 [语义版本](http://semver.org/). 每次发布需要做以下工作:

1.  为发行创建新分支, 命名为 `release/1.0.3` (何处) `1.0.3` 这是你释放的, 作为新版本.
2.  更新 `LIB_VERSION` 内 `src/connector/ably-connector.ts`。 。 。 .
3.  更新 `version` 内 `pakckage.json`。 。 。 .
4.  运行 [`github_changelog_generator`](https://github.com/github-changelog-generator/github-changelog-generator) 以自动更新 [变化中](https://npmcn.com/package/%40ably/CHANGELOG-ABLY.md)。这可能需要一些人工干预,无论是从命令的运行方式还是从修改更改日志文件的角度来说。 您的里程可能不同 :

-   您需要运行的命令 看起来像这样: `github_changelog_generator -u ably-forks -p laravel-echo --since-tag ably-echo-1.0.3 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS`生成符号 [这里](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token)。 。 。 .
-   用上面的命令, `--output delta.md` 写入在 `--since-tag` 到一个新的文件.
-   新文件的内容( :`delta.md`)然后需要手动插入到顶端 [变化中](https://npmcn.com/package/%40ably/CHANGELOG-ABLY.md),更改"未释放"标题并链接到当前版本编号.
-   还确保“Full Changelog”链接指向新版本标签,而不是 `HEAD`。 。 。 .

5.  提交生成 [变化中](https://npmcn.com/package/%40ably/CHANGELOG-ABLY.md) 文件为 root.
6.  做公关反对 `main`。 。 。 .
7.  公关批准后,合并为 `main`。 。 。 .
8.  添加标签并推到原产地 - 例如: `git tag ably-echo-1.0.3 && git push origin ably-echo-1.0.3`。 。 。 .
9.  在npmjs.com上发布npm包.
10.  访问 [https://github.com/able-forks/lalavel-echo/tags 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/ably-forks/laravel-echo/tags) 并添加发布后注释(一般您只需复制您添加到ChangGELOG中的注释).
11.  更新 [Ably 更改日志](https://changelog.ably.com/) (通过) [进步应用](https://headwayapp.co/))随着这些变化(再次,你只需复制你添加到变换组的音符).

## 说明

-   当前 `README` 新建并位于 `.github/README.md`。 。 。 .
-   `CHANGELOG-ABLY.md` 用于执行更改日志,而不是 `CHANGELOG.md`。 。 。 .
-   这主要是为了避免与基地寄存器冲突同步.

## 常见问题

### @ably/laravel-echo 是什么？

Laravel Echo 图书馆,用于美丽的 Ably 集成

### 如何安装 @ably/laravel-echo？

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

### @ably/laravel-echo 支持 TypeScript 吗？

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

### @ably/laravel-echo 支持 ESM 还是 CommonJS？

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

### @ably/laravel-echo 需要什么版本的 Node\.js？

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

### @ably/laravel-echo 可以商用吗？

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

### @ably/laravel-echo 的下载量有多少？

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

### @ably/laravel-echo 还在维护吗？

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