# @ably/react-web-cli 中文文档

规范地址：https://npmcn.com/package/%40ably/react-web-cli/

版本：1\.0\.0
npm 元数据更新时间：2026-10-14T11:06:15.058Z
中文译文更新时间：2026-11-06T17:52:39.088Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：301 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：react \>=17\.0\.0，react-dom \>=17\.0\.0
- 首次发布：2025-04-10T22:45:48.615Z
- 最新版本发布：2026-05-01T12:24:27.998Z
- 近 30 天下载量：2532（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 4 个）

## 中文简介

将 Ably CLI 嵌入网络终端的响应组件

## 安装

```sh
npm install @ably/react-web-cli
```

也可以使用：`pnpm add @ably/react-web-cli`、`yarn add @ably/react-web-cli`、`bun add @ably/react-web-cli`

## README

# @capaly/ react-web-cli (英语)

![npm (scoped)](https://img.shields.io/npm/v/@ably/react-web-cli) ![License](https://img.shields.io/github/license/ably/cli)

在网络应用程序中嵌入交互式Ably CLI终端的回放组件.

![Ably Web CLI demo screenshot](https://npmcn.com/package/%40ably/react-web-cli/assets/ably-web-cli-demo-screenshot.png)

## 特征

-   内嵌 a **ably CLI 完全定制** 任何 React app 中的会话( xterm.js) .
-   使用 HMAC 签名的认证连接 Ably 终端服务器的安全 WebSocket **签名配置** 财务报告和审定财务报表 **签名**。 。 。 .
-   一等站 UX:
    -   带有 ANSI 颜色的终端本地状态信息
    -   动画旋转器在( 重新) 连接时
    -   实况倒计时和清晰的指导(按下) **输入** 取消/重试)
    -   ASCII 重要状态信息模式框
-   强大的连接处理 :
    -   自动指数回放重接 (0 s, 2 s, 4 s, 8 s.)
    -   切换到手动重联之前可配置的最大重联尝试( 默认: 15)
    -   用特定错误代码妥善处理服务器启动的断开
-   **复会** 页面再装入或瞬间网络丢失(`resumeOnReload`) (中文(简体) ).
-   **分屏模式** 并同时有两个独立的终端会话.
-   工作在全屏或大抽屉中(见 `examples/web-cli`) (中文(简体) ).
-   以 TypeScript 写成, 完全可以树为轴 .

## 安装

```bash
# Using npm
npm install @ably/react-web-cli

# Using yarn
yarn add @ably/react-web-cli

# Using pnpm
pnpm add @ably/react-web-cli
```

## 先决条件

-   17.0.0以上反应
-   Ably CLI 终端服务器的运行实例(参见 [@cli-terminal-服务器](https://github.com/ably/cli-terminal-server)(中文(简体) )
-   生成HMAC签名证书的后端签名端点(见下文执行指南)

## 使用量

```tsx
import { useState, useEffect } from "react";
import { AblyCliTerminal } from "@ably/react-web-cli";

export default function MyTerminal() {
  const [status, setStatus] = useState("disconnected");
  const [signedConfig, setSignedConfig] = useState("");
  const [signature, setSignature] = useState("");

  // Sign credentials via your backend endpoint
  // See examples/web-cli/api/sign.ts for implementation reference
  async function signCredentials(apiKey: string) {
    const response = await fetch("/api/sign", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ apiKey }),
    });
    const { signedConfig, signature } = await response.json();
    setSignedConfig(signedConfig);
    setSignature(signature);
  }

  // Authenticate on mount (or when user provides credentials)
  useEffect(() => {
    const apiKey = "YOUR_ABLY_API_KEY"; // Get from user input or config
    signCredentials(apiKey);
  }, []);

  if (!signedConfig || !signature) {
    return <div>Loading...</div>;
  }

  return (
    <div style={{ height: 500 }}>
      <AblyCliTerminal
        websocketUrl="wss://web-cli.ably.com"
        signedConfig={signedConfig}
        signature={signature}
        initialCommand="ably --version"
        onConnectionStatusChange={setStatus}
        onSessionEnd={(reason) => console.log("session ended", reason)}
        onSessionId={(id) => console.log("session id", id)}
        resumeOnReload
        maxReconnectAttempts={15}
      />

      <p>Status: {status}</p>
    </div>
  );
}
```

## 道具

| Prop | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `websocketUrl` | 字符串 | ✅ | \- 说吧 | WebSocket 终端服务器的 URL |
| `signedConfig` | 字符串 | ✅ | \- 说吧 | JSON 编码的签名配置,包含证书和元数据(HMAC认证) |
| `signature` | 字符串 | ✅ | \- 说吧 | HMAC-SHA256 签名安全认证Config |
| `initialCommand` | 字符串 | 没有 | \- 说吧 | 启动时运行的命令 |
| `onConnectionStatusChange` | 函数 | 没有 | \- 说吧 | 当连接状态改变时召回 |
| `onSessionId` | 函数 | 没有 | \- 说吧 | 收到会话ID后召回 |
| `onSessionEnd` | 函数 | 没有 | \- 说吧 | 会话结束后调用 |
| `maxReconnectAttempts` | 编号 | 没有 | 15个 | 放弃前最大重联尝试 |
| `resumeOnReload` | 布尔 | 没有 | 虚假 | 是否尝试在重新装入页面后恢复已有会话 |
| `enableSplitScreen` | 布尔 | 没有 | 虚假 | 启用使用第二个独立终端的分屏模式 |

**说明:** 这个 `signedConfig` 财务报告和审定财务报表 `signature` 必须由 **您的后端** 使用HMAC-SHA256签名. 绝不在浏览器中签名 - 这将暴露您的签名秘密 .

**参考执行情况:**

-   **维塞尔:** 见 `examples/web-cli/api/sign.ts` 对于一个没有服务器的函数示例
-   **节点.js:** 见 `examples/web-cli/server/sign-handler.ts` 用于共享签名逻辑
-   **维特·德夫:** 见 `examples/web-cli/vite.config.ts` 用于开发中间软件

您的签名秘密必须符合终端服务器的 `SIGNING_SECRET` 配置 。 联系您的平台团队以获取这个秘密或参考 [终端服务器文档](https://github.com/ably/cli-terminal-server)。 。 。 .

## 执行签名终点

你个 **必须** 执行后端终点以签署证书。 这里有一个小例子:

```typescript
// Example: /api/sign endpoint (Node.js/Express/Vercel)
import crypto from "crypto";

export default function handler(req, res) {
  const { apiKey } = req.body;
  const secret = process.env.SIGNING_SECRET; // From environment variable

  // Build config object
  const config = {
    apiKey,
    timestamp: Date.now(),
  };

  // Sign it with HMAC-SHA256
  const configString = JSON.stringify(config);
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(configString);
  const signature = hmac.digest("hex");

  res.json({ signedConfig: configString, signature });
}
```

**安保要求:**

-   ⚠️ **从不** 在客户端代码中嵌入您的签名秘密
-   ⚠️ **永远** 在您的安全后端服务器上签名
-   QQ 签名密钥必须匹配终端服务器的配置
-   QQ 生产时使用 HTTPS 保护 API 键

**全面实施的实例:**

-   见 `examples/web-cli/` 完整工作示例目录
-   包括 Vercel 无服务器功能、 Vite dev 中间软件和 React 集成

## 中断更改和迁移

### HMAC 签名认证( 正在更改)

**这是一个突破性的变化.** 认证机制已经更新,以便使用HMAC签署的证书来改进安全.

**旧 API( 过期 ) :**

```tsx
<AblyCliTerminal
  websocketUrl="wss://web-cli.ably.com"
  ablyApiKey="YOUR_ABLY_API_KEY"           // ❌ Removed
  ablyAccessToken="YOUR_ABLY_TOKEN"        // ❌ Removed
  ablyEndpoint="nonprod:sandbox"           // ❌ Removed
  ablyControlHost="staging-control..."     // ❌ Removed
/>
```

**新建 API( 需要):**

```tsx
<AblyCliTerminal
  websocketUrl="wss://web-cli.ably.com"
  signedConfig={signedConfig}              // ✅ Required
  signature={signature}                    // ✅ Required
/>
```

**移徙步骤:**

1.  **执行后端签名 :** 创建一个 `/api/sign` 后端的端点(见上文“执行签名端点”部分)
2.  **获得签名秘密 :** 获取 `SIGNING_SECRET` 来自您的平台团队( 必须匹配终端服务器配置)
3.  **更新您的反应代码 :**
    -   删除旧道具 : `ablyApiKey`, (中文(简体) ), `ablyAccessToken`, (中文(简体) ), `ablyEndpoint`, (中文(简体) ), `ablyControlHost`
    -   打电话给你 `/api/sign` 要得到的终点 `signedConfig` 财务报告和审定财务报表 `signature`
    -   将签名的证书传递给 `AblyCliTerminal`

**为什么改变?**

新的由 HMAC 签名的认证可以防止证书被篡改,并确保配置设置(如端点和控制主机)由服务器认证. 这为嵌入式终端会话提供了更好的安全.

## 连接国

该组件管理多个连接, 声明您的应用程序可以响应 :

-   `initial`: 终端正在初始化
-   `connecting`: 试图连接到服务器
-   `connected`: 成功连接和准备
-   `disconnected`: 服务器或用户手动关闭的连接
-   `reconnecting`: 连接中断后试图重新连接
-   `error`: 连接错误或其他终端错误

## 服务器启动断接

终端以特定的 WebSocket 关闭代码妥善处理服务器启动的断开:

| 代码 | 说明 | 行为 |
| --- | --- | --- |
| 1 000个 | 正常关闭 | 在终端显示原因, 需要手动重接 |
| 1001 (简体中文) | 服务器离开 | 显示服务重启消息, 需要手动重接 |
| 1011号 | 服务器出错 | 显示出乎意料的条件消息, 需要手动重接 |
| 1013号 | 无服务 | 显示不可用服务消息, 需要手动重接 |
| 4000个 | 通用服务器断开 | 显示服务器提供的理由, 需要手动重接 |
| 4001 (英语) | 认证失败 | 显示带有指令的认证错误, 需要手动重接 |
| 第4008号 | 违反政策 | 显示认证超时/格式消息, 需要手动重接 |
| 第4429号 | 达到能力限制 | 使用 CLI 安装指令显示容量消息, 需要手动重接 |

对于其他WebSocket关闭代码,终端会自动尝试使用指数后退策略重新连接.

## 会话恢复

何时 `resumeOnReload` 启用,终端将把会话ID存储到 `sessionStorage` 并尝试在重新装入一页后恢复会话。 这使得在导航出行后和回行后可以进行无缝体验.

## 分块模式

何时 `enableSplitScreen` 设置为 `true`,组件在终端右上角显示一个分割图标。 点击此图标可以将视图分割为两个独立的终端会话并排.

分屏模式的特性 :

-   两个完全独立的终端会话,共享相同的证书
-   每个终端都有自己的有关闭按钮的标签
-   两个终端自动调整大小,以保持最佳布局
-   每个终端独立进行状态和连接管理
-   关闭任一终端返回到单页模式

该功能是为需要同时运行多条指令的开发者设计的,比如在一个面板上订阅一个频道,同时在另一个面板上发布.

## 设置终端服务器

此组件所需的终端服务器由单独的寄存器提供. 请参看 [@cli-terminal-服务器](https://github.com/ably/cli-terminal-server) 用于:

-   安装指令
-   配置选项
-   本地运行服务器
-   Docker 部署指令

用于生产,Ably网络CLI连接到 `wss://web-cli.ably.com` 默认情况下,这是终端服务器的主机实例.

## 页:1

-   航站楼需要一个容器来进行尺寸,所以要确保母元素有被定义的高度和宽度.
-   该组件会用指数回放自动处理重联.
-   仅 `ably`, (中文(简体) ), `clear`,以及 `exit` 命令默认在终端中可用.
-   终端支持完整的xterm.js功能,包括颜色和Unicode.

## 调试Verbose 日志( V)

装有内置动词记录器的部件船 **默认禁用**。 。 。 . 以下列任何方式启用 _在此之前_ 组件挂载 :

1.  **查询字符串旗** - 简单添加 `?cliDebug=true` 到页面 URL. 示例 `http://localhost:5173/?cliDebug=true` (国旗可与其他查询参数合并
    
2.  **运行时全球旗帜** - 从浏览器 DevTools 控制台运行:
    

```js
window.ABLY_CLI_DEBUG = true;
```

终端将发布详细寿命周期日志,其前缀为 `[AblyCLITerminal DEBUG]`。删除旗帜或刷新而无需查询 参数返回到无声模式.

## 示例项目

使用该组件的完整实例,见 [网络 cli 实例](https://github.com/ably/ably-cli/tree/main/examples/web-cli) 在 Ably CLI 存储器中.

## 发展

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test
```

## 许可证

[阿帕奇 - 2.0](https://github.com/ably/ably-cli/blob/main/LICENSE)

## 常见问题

### @ably/react-web-cli 是什么？

将 Ably CLI 嵌入网络终端的响应组件

### 如何安装 @ably/react-web-cli？

在项目目录运行 npm install @ably/react-web-cli，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=17\.0\.0）、react-dom（\>=17\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ably/react-web-cli 支持 TypeScript 吗？

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

### @ably/react-web-cli 支持 ESM 还是 CommonJS？

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

### @ably/react-web-cli 可以商用吗？

@ably/react-web-cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ably/react-web-cli 的下载量有多少？

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

### @ably/react-web-cli 还在维护吗？

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