微信 / 支付宝 / 抖音小程序的 socket.io 客户端：直接复用官方 socket.io-client，仅把底层 WebSocket transport 换成小程序原生实现，API 与官方完全一致，严格对齐 socket.io v4。
- 三端：微信 / 支付宝 / 抖音（及今日头条等字节系），运行时自动探测
wx/my/tt，无需手动区分平台 - 协议 100% 对齐 v4：基于官方
socket.io-client，namespace / ACK / 重连 / 二进制 / 多路复用全部原生支持 - 零协议重写：只替换 transport 层，行为与官方一致，升级 socket.io 即可获得新能力
- 自带类型：TypeScript 编写，产物 ESM + CJS +
.d.ts，开箱即用 - 可扩展：支持注入自定义 transport（Taro / uni-app 等）
npm i socket.io-mp
# 或
pnpm add socket.io-mp
# 或
yarn add socket.io-mp
socket.io-client是本包的运行时依赖（dependencies），会随本包自动安装，无需单独安装。仅当你想在代码里直接 import 它（例如引用Socket类型）或自行锁定版本时，再显式安装socket.io-client。
import { io } from 'socket.io-mp'
const socket = io('wss://example.com', { auth: { token: 'xxx' } })
socket.on('connect', () => console.log('connected', socket.id))
socket.on('news', (data) => console.log(data))
socket.emit('msg', { a: 1 }, (ack) => console.log('ack:', ack))io() 会自动探测当前小程序平台、注入对应 transport，并强制只走 websocket，其余一切与官方 socket.io-client 相同。
你也可以用默认导出：
import io from 'socket.io-mp'。二者等价，按喜好二选一。
下面只列出常用片段；完整 API 直接参考 socket.io 官方客户端文档，本包与之一致。
socket.on('connect', () => {})
socket.on('disconnect', (reason) => {})
socket.on('chat', (msg) => console.log(msg))
socket.emit('chat', { text: 'hi' })
socket.off('chat') // 取消监听服务端在收到事件后可以回传一个 ACK：
// 普通 ACK
socket.emit('order', { id: 1 }, (resp) => {
console.log('服务端回执:', resp)
})
// 带超时的 ACK（v4）：5s 内没回执则 err 非空
socket.timeout(5000).emit('order', { id: 1 }, (err, resp) => {
if (err) console.warn('ACK 超时')
else console.log(resp)
})在 uri 后面加路径即可连接到对应 namespace：
const admin = io('wss://example.com/admin', { auth: { token } })
admin.on('welcome', (msg) => console.log(msg))直接 emit / 接收 ArrayBuffer（或 TypedArray）。微信、抖音走原生 ArrayBuffer，支付宝内部用 base64 编解码，对调用方透明：
const bytes = new Uint8Array([1, 2, 3, 4])
socket.emit('upload', bytes.buffer, (ack) => console.log(ack))
socket.on('chunk', (buf: ArrayBuffer) => {
console.log(new Uint8Array(buf))
})小程序对自定义请求头支持有限（支付宝的 connectSocket 不支持 header，部分 header 也被平台限制），请优先用 auth（CONNECT 包）或 query，而不是自定义 header：
// 推荐：auth 随 CONNECT 包发送，可在服务端 io.use 中读取
io('wss://example.com', { auth: { token: 'xxx' } })
// 或放进 query
io('wss://example.com', { query: { uid: '42' } })重连相关选项与官方一致，直接透传：
const socket = io('wss://example.com', {
reconnection: true,
reconnectionAttempts: 5,
reconnectionDelay: 1000,
})
socket.io.on('reconnect_attempt', (n) => console.log('第', n, '次重连'))
socket.disconnect() // 主动断开
socket.connect() // 重新连接| 项目 | 说明 |
|---|---|
| 仅 websocket | 小程序无 HTTP polling；transport 固定为 websocket（无需也无法配置 polling 回退） |
| 鉴权方式 | 用 auth（CONNECT 包）或 query，而非自定义 header |
| 合法域名 | 需在小程序后台配置 socket 合法域名（wss://…），真机才能连接 |
其余 API（namespace / ACK / 重连 / 二进制 / 多路复用 / timeout 等）与官方完全一致。
| 平台 | 连接 API | 并发 | 二进制 |
|---|---|---|---|
| 微信小程序 | wx.connectSocket（返回 SocketTask） |
多连接 | 原生 ArrayBuffer |
| 支付宝小程序 | my.connectSocket({ multiple: true })（返回 SocketTask） |
多连接 | base64 编解码（对调用方透明） |
| 抖音小程序（字节系） | tt.connectSocket（返回 SocketTask） |
多连接 | 原生 ArrayBuffer |
运行时通过 wx / my / tt 全局对象自动探测；tt 为整个字节系小程序（抖音 / 今日头条 / 西瓜 / 极速版等）共用。多端共存时优先级 微信 > 支付宝 > 抖音。
在 Taro、uni-app 等框架里，如果运行时仍然存在 wx / my / tt 全局（编译到小程序端通常如此），可直接使用，无需额外配置。
若运行在没有 wx / my / tt 的环境（如编译到 H5 / RN），或想接入其它平台，可显式传入自定义 Transport 类跳过自动探测：
import { io } from 'socket.io-mp'
import { MyTaroTransport } from './my-taro-transport'
io('wss://example.com', { transports: [MyTaroTransport] })自定义 Transport 需继承 engine.io-client 的 Transport，实现：
get name()— 返回'websocket'doOpen/doClose/write- 在底层连接的事件回调里调用基类的
onOpen/onData/onClose/onError
可直接参考仓库内的 src/transports/wechat.ts、src/transports/alipay.ts、src/transports/douyin.ts。
在小程序里创建一个 socket.io 连接。
uristring— 服务端地址，可带 namespace，如wss://example.com或wss://example.com/adminoptsMpOptions—（可选）等价于官方Partial<ManagerOptions & SocketOptions>，外加：transports?TransportCtor[]— 覆盖自动探测，显式注入自定义 transport（见上文）
- 返回 官方
Socket实例
// io 同时是默认导出和具名导出，二选一即可
import { io } from 'socket.io-mp'
// import io from 'socket.io-mp'
import {
Manager,
Socket, // 透传官方类
WechatTransport, // 微信 transport（一般无需直接用）
AlipayTransport, // 支付宝 transport
DouyinTransport, // 抖音 / 字节系 transport
} from 'socket.io-mp'
import type {
MpOptions,
TransportCtor,
ManagerOptions,
SocketOptions,
} from 'socket.io-mp'连不上 / 一直 connect_error？
先确认已在小程序后台「开发管理 → 服务器域名」里配置了 socket 合法域名（wss://…），且真机/体验版生效；本地开发可在开发者工具勾选「不校验合法域名」。
报错 未检测到 wx/my/tt 的 WebSocket API？
说明当前运行环境没有 wx / my / tt 全局（例如在 H5、Node、纯浏览器里跑）。请在小程序端运行，或通过 io(uri, { transports: [自定义Transport] }) 显式注入 transport。
自定义 header 不生效？
这是平台限制，详见鉴权：请改用 auth 或 query 传递鉴权信息。