> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# connectSocket

创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。

该 API 会同步返回 `SocketTask`，但连接创建本身是异步过程。调用方应先在返回的
`SocketTask` 上注册事件回调，再等待 `onOpen` 表示连接可用。后续发送消息使用
`SocketTask.send`，关闭连接使用 `SocketTask.close`。

## 扫码预览

![扫码预览 connectSocket](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fnetwork%252Fconnect-socket%252Findex)

## 支持版本

前端库版本不低于 `0.0.30`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>不支持</td></tr>
</tbody>
</table>

## 使用说明

- 返回 `SocketTask` 不代表连接已经成功，连接成功以 `onOpen` 为准。

- `send` 必须接收对象参数，并把要发送的内容放在 `data` 字段中。

- 如果 `protocols` 非空，需要服务端支持并返回匹配的子协议。

- 多次调用会创建多条连接，旧连接不会自动关闭；不再使用时应主动调用 `close`。

- 连接失败、发送失败或关闭失败会通过 `SocketTask.onError` 通知。

- 不再使用的连接应主动调用 SocketTask.close 释放资源，避免占用连接名额。

## 调用方式

### 同步 API

```typescript
connectSocket(params: ConnectSocketParams): SocketTask
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>WebSocket 握手阶段携带的 HTTP Header。<br><br>适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。<br>`referer` 由豆包客户端统一生成和管理，不应依赖该字段被业务传入值覆盖。</td></tr>
<tr><td><code>protocols</code></td><td><code>string[]</code></td><td>否</td><td><code>-</code></td><td>-</td><td>WebSocket 子协议数组。<br><br>会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。<br>如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回；<br>服务端不支持或不返回匹配协议时，豆包客户端可能判定连接创建失败。</td></tr>
<tr><td><code>url</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>WebSocket 连接地址。<br><br>需要包含协议、域名、路径和可选 query，例如 `wss://example.com/socket?room=1`。<br>如果地址为空或不是字符串，本 API 会返回 `readyState` 为 `undefined` 的 SocketTask，<br>并异步触发 `onError`。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
import { connectSocket } from '@doubao-dev/framework/api';

const socketTask = connectSocket({
  url: 'wss://example.com/socket',
  header: { authorization: 'Bearer token' },
  protocols: ['chat.v1']
});

socketTask.onOpen(() => {
  socketTask.send({ data: 'hello' });
});

socketTask.onMessage((event) => {
  console.log(event.data);
});

socketTask.onClose((event) => {
  console.log(event.code, event.reason);
});

socketTask.onError((event) => {
  console.error(event.errMsg);
});
```

## 返回值

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>close</code></td><td><code>(params?: SocketTaskCloseParams) =&gt; void</code></td><td>是</td><td>关闭 WebSocket 连接。<br><br>调用后会发起关闭动作，并把 `readyState` 置为 `SocketTask.CLOSING`。<br>最终关闭完成时触发 `onClose`；关闭动作失败时触发 `onError`。</td></tr>
<tr><td><code>CLOSED</code></td><td><code>3</code></td><td>是</td><td>表示 Socket 连接已关闭。<br><br>进入该状态后，该任务不会再收到新的消息，也不应继续调用 `send`。</td></tr>
<tr><td><code>CLOSING</code></td><td><code>2</code></td><td>是</td><td>表示 Socket 连接关闭中。<br><br>调用 SocketTask.close 后，等待豆包客户端完成关闭流程时通常处于该状态。</td></tr>
<tr><td><code>CONNECTING</code></td><td><code>0</code></td><td>是</td><td>表示 Socket 正在连接。<br><br>`connectSocket` 刚返回且豆包客户端尚未完成握手时通常处于该状态。</td></tr>
<tr><td><code>onClose</code></td><td><code>(callback: (event: SocketTaskCloseEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 与服务器连接断开的事件。<br><br>主动关闭、服务端关闭、连接被回收都可能触发该回调。<br>回调触发后当前任务已经结束，不应继续使用。</td></tr>
<tr><td><code>onError</code></td><td><code>(callback: (event: SocketTaskErrorEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 发生错误的事件。<br><br>连接创建、发送、关闭或 WebSocket 通道出现异常时触发。<br>该回调只表示发生错误，不等同于连接一定已经关闭；是否关闭应结合 `readyState`<br>或后续 `onClose` 事件判断。</td></tr>
<tr><td><code>onMessage</code></td><td><code>(callback: (event: SocketTaskMessageEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 接收到服务器发送信息的事件。<br><br>服务端每下发一条消息都会触发一次回调。消息内容通过 `event.data` 返回，<br>类型可能是 `string` 或 `ArrayBuffer`。</td></tr>
<tr><td><code>onOpen</code></td><td><code>(callback: (event: SocketTaskOpenEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 连接服务器成功的事件。<br><br>可以注册多个回调。连接成功后触发回调，并携带握手响应 Header、协议类型等信息。<br>通常应在该回调中或之后调用 `send`。</td></tr>
<tr><td><code>OPEN</code></td><td><code>1</code></td><td>是</td><td>表示 Socket 连接已经打开。<br><br>进入该状态后可以调用 SocketTask.send 发送数据。</td></tr>
<tr><td><code>readyState</code></td><td><code>number | undefined</code></td><td>是</td><td>当前 Socket 连接状态 code。<br><br>可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。<br>如果因为参数错误等原因导致豆包客户端没有成功创建连接，则为 `undefined`。</td></tr>
<tr><td><code>send</code></td><td><code>(params: SocketTaskSendParams) =&gt; void</code></td><td>是</td><td>通过 WebSocket 连接发送数据。<br><br>该方法只发起发送动作，不返回发送结果。建议在 `readyState === SocketTask.OPEN`<br>或收到 `onOpen` 事件后调用；如果连接未就绪、数据编码失败或发送失败，<br>会触发 `onError`。</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "readyState": 0
}
```

## 错误处理

同步调用失败时抛出错误。错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errNo": 1501001,
  "errMsg": "websocket connection limit exceeded"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>创建连接时 url 为空或非 ws/wss，或调用 send 时 base64 数据非法、dataType 不支持</td><td>传入合法的 ws/wss url 与受支持的发送数据后重试。</td></tr>
<tr><td><code>110</code></td><td><code>API call prohibited</code></td><td>Android、iOS</td><td>socket url 未通过域名白名单校验</td><td>确认目标域名已在应用插件中配置后重试。</td></tr>
<tr><td><code>116</code></td><td><code>resource not found</code></td><td>Android、iOS</td><td>对已关闭或不存在的 socketTaskId 调用 send/close</td><td>仅在 onOpen 后、onClose 前操作连接，不要复用已关闭的连接。</td></tr>
<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>建立连接、发送或关闭过程中发生网络错误</td><td>检查网络连接，必要时重新建立连接。</td></tr>
<tr><td><code>1501001</code></td><td><code>websocket connection limit exceeded</code></td><td>Android、iOS</td><td>同一应用插件的 WebSocket 连接数超过上限</td><td>关闭不再使用的连接后重试。</td></tr>
<tr><td><code>1501002</code></td><td><code>websocket is not open</code></td><td>iOS</td><td>连接尚未打开或已关闭时调用 send</td><td>在收到 onOpen 事件后再发送数据。</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android</td></tr>
<tr><td><code>113</code></td><td><code>bridge unavailable</code></td><td>JS API 暂不可用</td><td>Android、iOS</td></tr>
</tbody>
</table>

## 平台差异

- **Android**：建立连接失败统一返回 102；send 在连接未打开时返回 305 或 116。
- **iOS**：send 在连接未打开时返回 1501002。

## 已知限制与注意事项

- 同一应用插件内最多同时保持 5 条 WebSocket 连接，超过上限时 connectSocket 会立即同步失败并通过 SocketTask.onError 通知。
