快速开始

安装

pnpm add @aemeath-projects/napcat

基础用法

1. 创建 Transport

NapCat SDK 支持四种连接方式，选择适合你的场景：

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

// 正向 WebSocket：SDK 主动连接 NapCat
const transport = new WebSocketTransport({
  url: 'ws://localhost:3001',
  token: 'your-access-token',
  reconnect: {
    initialDelay: 1000,  // 初始重连延迟 (ms)
    maxDelay: 30000,     // 最大重连延迟 (ms)
  },
})

其他 Transport 的完整配置参见连接方式。

2. 初始化客户端

import { NapCatClient, MessageApi, GroupApi, Seg } from '@aemeath-projects/napcat'

const client = new NapCatClient(transport)
const msg = new MessageApi(client)
const group = new GroupApi(client)

3. 监听事件

// 监听群消息
client.on('message.group', async (event) => {
  console.log(`群 ${event.group_id} 收到消息: ${event.raw_message}`)
})

// 监听私聊消息
client.on('message.private', async (event) => {
  console.log(`来自 ${event.sender.nickname}: ${event.raw_message}`)
})

// 监听错误
client.on('error', (err) => {
  console.error('连接异常:', err.message)
})

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

4. 建立连接

try {
  await client.connect()
  console.log('连接成功')
} catch (err) {
  console.error('连接失败:', err)
}

Result 类型

所有 API 方法返回 Result<T> 类型，使用前始终检查 result.ok：

const result = await msg.sendGroupMsg(123456789, [Seg.text('hello')])

if (result.ok) {
  console.log('发送成功，message_id:', result.data.message_id)
} else {
  console.error('发送失败，code:', result.error.code, 'message:', result.error.message)
}

事件类型列表

client.on() 可监听以下事件：

事件名	触发时机
connect	连接建立
close	连接断开
error	连接错误
reconnecting	正在重连
message	收到消息（私聊或群聊）
message.private	收到私聊消息
message.group	收到群聊消息
message_sent	机器人自发消息（NapCat 扩展）
notice	所有通知事件
notice.friend_add	好友添加
notice.friend_recall	好友消息撤回
notice.group_increase	群成员增加
notice.group_decrease	群成员减少
notice.group_ban	群禁言
notice.group_admin	群管理员变更
notice.group_upload	群文件上传
notice.group_recall	群消息撤回
notice.group_card	群名片变更
notice.essence	精华消息
notice.group_msg_emoji_like	群消息表情回应
notice.notify	通知子事件（戳一戳等）
notice.bot_offline	机器人下线
request	所有请求事件
request.friend	好友添加请求
request.group	加群请求/邀请
meta_event	所有元事件
meta_event.lifecycle	生命周期事件
meta_event.heartbeat	心跳事件

错误处理最佳实践

import { NapCatError, ConnectionError, TransportError, TimeoutError } from '@aemeath-projects/napcat'

// 区分不同类型的错误
client.on('error', (err) => {
  if (err instanceof ConnectionError) {
    console.error('连接错误，检查 NapCat 是否运行:', err.message)
  } else if (err instanceof TimeoutError) {
    console.error('API 调用超时:', err.message)
  } else if (err instanceof TransportError) {
    console.error('传输层错误:', err.message)
  } else {
    console.error('未知错误:', err)
  }
})

// API 调用错误处理
async function safeCall<T>(promise: Promise<Result<T>>): Promise<T | null> {
  const result = await promise
  if (!result.ok) {
    console.warn(`API 调用失败 (${result.error.code}): ${result.error.message}`)
    return null
  }
  return result.data
}

const data = await safeCall(msg.sendGroupMsg(groupId, [Seg.text('hi')]))
if (data) {
  console.log('消息已发送, id:', data.message_id)
}

每种 Transport 的最小可用示例

正向 WebSocket

import { NapCatClient, WebSocketTransport, MessageApi, Seg } from '@aemeath-projects/napcat'

const transport = new WebSocketTransport({ url: 'ws://localhost:3001' })
const client = new NapCatClient(transport)
const msg = new MessageApi(client)

client.on('message.group', async (e) => {
  await msg.sendGroupMsg(e.group_id, [Seg.text('pong')])
})

await client.connect()

反向 WebSocket

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

const transport = new ReverseWebSocketTransport({ port: 8080 })
const client = new NapCatClient(transport)
// 配置 NapCat 连接 ws://你的地址:8080

await client.connect()

HTTP

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

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

await client.connect()

SSE

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

const transport = new SseTransport({
  baseUrl: 'http://localhost:3000',
  reconnect: { initialDelay: 1000 },
})
const client = new NapCatClient(transport)

await client.connect()

下一步

• 了解所有连接方式
• 查看消息段类型
• 浏览 API 参考