连接方式

NapCat SDK 支持四种 Transport，覆盖不同的网络拓扑场景。

Transport 对照

Transport	方向	适用场景
WebSocketTransport	正向 WS：SDK → NapCat	SDK 主动连接 NapCat 实例
ReverseWebSocketTransport	反向 WS：NapCat → SDK	NapCat 主动连接 SDK 服务
HttpTransport	HTTP + 事件上报	HTTP 调用 + NapCat 推送事件
SseTransport	HTTP-SSE	HTTP 调用 + SSE 事件推送

WebSocketTransport

正向 WebSocket：SDK 作为客户端主动连接 NapCat WebSocket 服务。

构造函数

new WebSocketTransport(options: WebSocketTransportOptions)

配置选项

选项	类型	必填	默认值	说明
url	string	是	—	WebSocket 服务器地址，如 ws://127.0.0.1:3001
token	string	否	—	NapCat access token，非空时附加到 URL 查询参数
timeout	number	否	10000	API 调用超时（ms）
reconnect	ReconnectOptions	否	—	重连策略配置，不传则不自动重连

示例

import { WebSocketTransport } from '@aemeath-projects/napcat'

const transport = new WebSocketTransport({
  url: 'ws://localhost:3001',
  token: 'your-access-token',
  timeout: 10000,
  reconnect: {
    initialDelay: 1000,
    maxDelay: 30000,
  },
})

ReverseWebSocketTransport

反向 WebSocket：SDK 启动 WebSocket Server，等待 NapCat 主动连接。

构造函数

new ReverseWebSocketTransport(options: ReverseWebSocketTransportOptions)

配置选项

选项	类型	必填	默认值	说明
port	number	是	—	监听端口，0 表示由 OS 分配随机可用端口
host	string	否	'127.0.0.1'	监听主机
path	string	否	'/'	WebSocket 路径
token	string	否	—	NapCat access token，非空时校验连接方提供的 token
maxConnections	number	否	1	最大并发连接数
timeout	number	否	10000	API 调用超时（ms）

属性

属性	类型	说明
port	number	已绑定的实际端口（port=0 时由 OS 分配）
url	string	外部可连接的 WS URL（含 host、port、path）

示例

import { ReverseWebSocketTransport } from '@aemeath-projects/napcat'

const transport = new ReverseWebSocketTransport({
  port: 8080,
  token: 'your-access-token',
})

console.log('等待 NapCat 连接:', transport.url)

HttpTransport

HTTP Transport：API 调用通过 HTTP POST 发送，事件接收通过内置 HTTP server。

构造函数

new HttpTransport(options: HttpTransportOptions)

配置选项

HttpTransportOptions

选项	类型	必填	默认值	说明
apiBaseUrl	string	是	—	NapCat HTTP API 基础地址，如 http://127.0.0.1:3000
token	string	否	—	NapCat access token，非空时附加到请求头
eventServer	HttpEventServerOptions	是	—	SDK 侧 event server 配置

HttpEventServerOptions

选项	类型	必填	默认值	说明
port	number	是	—	监听端口，0 表示由 OS 分配随机可用端口
host	string	否	'127.0.0.1'	监听主机
path	string	否	'/onebot/event'	事件上报路径

属性

属性	类型	说明
eventServerPort	number	已绑定的 event server 实际端口

示例

import { HttpTransport } from '@aemeath-projects/napcat'

const transport = new HttpTransport({
  apiBaseUrl: 'http://localhost:3000',
  token: 'your-access-token',
  eventServer: {
    port: 8080,
    path: '/onebot/event',
  },
})
// 在 NapCat 配置中将事件上报地址设为 http://你的地址:8080/onebot/event

注意：connect() 启动 event server 后会自动调用 get_login_info 做健康检查，失败则抛出 ConnectionError。

SseTransport

SSE Transport：API 调用走 HTTP POST，事件接收走 GET /_events SSE 连接。

构造函数

new SseTransport(options: SseTransportOptions)

配置选项

选项	类型	必填	默认值	说明
baseUrl	string	是	—	NapCat SSE 基础地址，如 http://127.0.0.1:3000
token	string	否	—	NapCat access token，非空时附加到 Authorization header
reconnect	ReconnectOptions	否	—	断线重连配置，不传则不自动重连

示例

import { SseTransport } from '@aemeath-projects/napcat'

const transport = new SseTransport({
  baseUrl: 'http://localhost:3000',
  token: 'your-access-token',
  reconnect: {
    initialDelay: 1000,
    maxDelay: 30000,
  },
})

重连机制

WebSocketTransport 和 SseTransport 支持可选的自动重连，通过 reconnect 配置。

ReconnectOptions

选项	类型	必填	默认值	说明
initialDelay	number	否	1000	初始延迟（ms）
maxDelay	number	否	30000	最大延迟（ms）
multiplier	number	否	2	退避倍数
jitter	number	否	0.1	抖动因子 0~1，添加随机性避免惊群
maxRetries	number	否	-1	最大重试次数，-1 为无限

指数退避算法

delay = min(initialDelay * multiplier^attempts, maxDelay)
delay += random(-jitter, +jitter) * delay  // 添加抖动

• 连接成功后调用 reset() 重置计数器
• maxRetries = -1 时无限重试
• 主动调用 disconnect() 不会触发重连
• 每次重连前会 emit reconnecting(attempt, delay) 事件

重连示例

import { WebSocketTransport } from '@aemeath-projects/napcat'

const transport = new WebSocketTransport({
  url: 'ws://localhost:3001',
  reconnect: {
    initialDelay: 500,    // 首次重连等待 500ms
    maxDelay: 10000,       // 最长等待 10s
    multiplier: 2,         // 每次翻倍
    jitter: 0.2,           // ±20% 抖动
    maxRetries: 10,        // 最多重试 10 次
  },
})

transport.on('reconnecting', (attempt, delay) => {
  console.log(`第 ${attempt} 次重连，${delay}ms 后`)
})