更新记录

1.0.0（2026-08-11）

• 1.0.0：首版，包含 HTTP / WebSocket / MQTT / SSE / TCP / UDP 六协议与拦截器、重连、Token 刷新、流式输出等能力。
• 更新时修改 uni_modules/net-client/package.json 的 version，并在 changelog.md 追加记录，重新执行 node scripts/sync-uni-module.js 同步后再次发布。

平台兼容性

uni-app(3.8.1)

uni-app x(3.8.1)

net-client

uni-app 跨端通用接口连接工具库 —— HTTP / WebSocket / MQTT / SSE / TCP / UDP 六种协议，一套 API 全部搞定。 100% TypeScript 编写，面向对象架构，开箱即用的拦截器、心跳重连、Token 自动刷新与 AI 流式打字机。

[]() []() []()

为什么需要它

在 uni-app 项目里，网络层通常是这样长起来的：utils/request.js 里塞一个 uni.request 封装， 再来个 socket.js 写一堆 setInterval 心跳，MQTT 在小程序上跑不起来只好换协议， 接入大模型时又发现流式输出在小程序端一片乱码……

本库把这些坑一次性填平：

安装

方式一：uni_modules（推荐）

在 DCloud 插件市场 点击「下载插件并导入 HBuilderX」， 插件会自动放到项目的 uni_modules/net-client 目录，无需其它配置。

import net from '@/uni_modules/net-client'

方式二：npm

npm i net-client
# 需要 MQTT 时再装（可选依赖，不用就不会进包体）
npm i mqtt@4

import net from 'net-client'

兼容性

¹ 微信小程序需在后台配置 TCP/UDP 合法域名。 ² 取决于各家小程序是否实现 enableChunked，未实现时自动降级为一次性返回。

快速上手

1. 全局初始化（main.ts）

import net from 'net-client'

net.http.setBaseURL('https://api.your-domain.com')
net.http.defaults.timeout = 20000
net.setDebug(process.env.NODE_ENV !== 'production')   // 调试日志总开关

// Token 自动注入 + 401 自动刷新
net.http.setAuth({
  getToken: () => uni.getStorageSync('access_token'),
  refresh: async () => {
    const { data } = await net.http.post('/auth/refresh',
      { refreshToken: uni.getStorageSync('refresh_token') },
      { skipInterceptors: true, skipAuth: true })   // 避免递归
    uni.setStorageSync('access_token', data.accessToken)
    return data.accessToken
  },
  onRefreshFailed: () => uni.reLaunch({ url: '/pages/login/index' })
})

// 业务码拆包
net.http.interceptors.response.use((res) => {
  if (res.data?.code === 0) return { ...res, data: res.data.data }
  throw new Error(res.data?.message || '请求失败')
})

2. 发请求

const { data } = await net.http.get<User>('/user/profile', { params: { id: 1 } })
await net.http.post('/order', { skuId: 1 })

// 取消
const task = net.http.get('/slow')
task.abort()

// 重试（指数退避）
net.http.get('/flaky', { retry: { retries: 3, baseDelay: 500 } })

// 搜索防抖：同 dedupeKey 的旧请求自动取消
net.http.get('/search', { params: { kw }, dedupeKey: 'search' })

3. WebSocket

const ws = net.ws('chat', {
  url: 'wss://your-domain.com/ws',
  query: () => ({ token: uni.getStorageSync('access_token') }),
  heartbeat: { interval: 25000, timeout: 10000, isPong: (d) => d?.type === 'pong' },
  reconnect: { baseDelay: 1000, maxDelay: 30000, factor: 1.8 }
})

ws.onOpen(({ reconnected }) => console.log(reconnected ? '重连成功' : '连接成功'))
ws.onMessage<{ content: string }>(({ data }) => console.log(data.content))
ws.connect()
ws.send({ type: 'chat', content: 'hello' })   // 未连接时自动进离线队列

4. AI 流式输出

const { result, abort } = net.aiStream({
  url: 'https://api.deepseek.com/chat/completions',
  header: { Authorization: `Bearer ${key}` },
  data: { model: 'deepseek-chat', stream: true, messages },
  onDelta: (delta, full) => (answer.value = full)   // 打字机效果
})
// 停止生成
abort()

5. MQTT

import mqtt from 'mqtt/dist/mqtt.min.js'

const client = net.mqtt('device', { url: 'wss://broker:8084/mqtt', mqttLib: mqtt })
await client.connect()
await client.onTopic('device/+/telemetry', (payload) => console.log(payload))
await client.publish('device/1001/cmd', { cmd: 'light', value: 1 }, { qos: 1 })

6. 局域网设备发现（TCP / UDP）

// UDP 广播发现
const udp = net.udp()
udp.bind()
const devices = await udp.discover({
  port: 6000,
  probe: 'WHO_IS_THERE',
  duration: 3000,
  identify: (m) => m.remoteInfo.address
})

// TCP 直连
const tcp = net.tcp()
await tcp.connect({ host: '192.168.1.100', port: 8899 })
tcp.on('data', ({ text }) => console.log(text))
tcp.write('AT+STATUS\r\n')

完整可运行示例见 examples/ 目录： net.config.ts（全局配置）、http-demo.vue、websocket-demo.vue、ai-stream-demo.vue、mqtt-demo.vue。

架构

src/
├── index.ts                 统一导出入口（默认单例 net + 全部类型）
├── core/
│   ├── client.ts            NetClient 门面：托管全部协议实例与生命周期
│   ├── http.ts              HttpClient：拦截器 / 重试 / 取消 / Token 刷新
│   ├── websocket.ts         WebSocketClient：心跳 / 退避重连 / 离线队列
│   ├── mqtt.ts              MqttClient：订阅管理 / 通配符路由 / 断线恢复
│   ├── sse.ts               SSEClient + SSEParser + createAIStream
│   ├── socket.ts            TcpSocketClient / UdpSocketClient
│   └── interceptor.ts       拦截器管理器
├── adapters/
│   └── ws-polyfill.ts       uni.connectSocket → W3C WebSocket 垫片
├── shared/
│   ├── emitter.ts           类型安全的发布订阅基类
│   ├── errors.ts            NetError + 错误码枚举 + 文案国际化
│   ├── logger.ts            分级日志 / 全局开关 / 自定义上报
│   ├── platform.ts          运行时与平台探测、网络状态监听
│   ├── cancel.ts            CancelToken
│   └── utils.ts             URL / 退避 / 流式 UTF-8 解码
└── types/index.ts           全部对外 Interface 定义

单例与多实例：

import net, { createInstance } from 'net-client'

net.http.get('/a')                                        // 默认单例
const b = createInstance({ http: { baseURL: 'https://b.com' } })   // 隔离实例
b.http.get('/c')

net.stats()      // 查看当前所有连接状态，方便做调试面板
await net.destroy()   // 退出登录：一键回收全部连接

API 参考

HttpClient

RequestConfig 常用字段

关于 extra：RequestConfig 刻意没有声明 [key: string]: any 索引签名。 带索引签名的接口一旦经过 Omit<T, K>（get/post/upload 的配置参数正是这么派生的）， keyof 会退化成 string | number，导致所有具名属性被抹平、配置项写错也不报错。 因此平台私有参数统一走 extra，换来的是 http.get('/a', { timeoutt: 1000 }) 这类拼写错误能在编译期被抓住。

net.http.get('/a', { extra: { someVendorOnlyFlag: true } })

AuthAdapter

WebSocketClient

SocketOptions

MqttClient

小程序注意事项

1. 必须使用 wss://（如 EMQX 的 8084 端口，路径通常为 /mqtt）
2. 在小程序管理后台把 broker 域名加入 socket 合法域名
3. mqttLib 请传 mqtt/dist/mqtt.min.js（浏览器构建），Node 版会因缺少 net 模块报错

SSEClient / createAIStream

createAIStream 额外支持 onDelta(delta, full, ev)、onDone(full)、onError、pickDelta。 默认 pickDelta 已兼容：OpenAI / DeepSeek / Kimi / 智谱（choices[0].delta.content）、 Anthropic（content_block_delta）、DashScope 通义（output.text）。私有协议自行传入即可。

错误处理

import { isNetError, NetErrorCode } from 'net-client'

try {
  await net.http.get('/x')
} catch (e) {
  if (isNetError(e)) {
    console.log(e.code)        // NetErrorCode.TIMEOUT
    console.log(e.statusCode)  // HTTP 状态码（非 HTTP 错误为 undefined）
    console.log(e.data)        // 服务端返回的响应体（如果有）
    console.log(e.detail)      // { url, statusCode, cause, … } 完整上下文
    console.log(e.retryable)   // 是否可重试
    console.log(e.isAbort, e.isTimeout)
  }
}

错误码分组：通用 E_TIMEOUT / E_NETWORK / E_ABORTED / E_PARSE …、 HTTP E_HTTP_STATUS / E_HTTP_UNAUTHORIZED / E_HTTP_TOKEN_REFRESH_FAILED …、 WebSocket E_WS_*、MQTT E_MQTT_*、SSE E_SSE_*、Socket E_SOCKET_*。

支持文案国际化：

import { setErrorMessages, NetErrorCode } from 'net-client'
setErrorMessages({ [NetErrorCode.NETWORK]: 'Network unavailable' })

日志

import { setDebug, setLogLevel, setLogTransport, LogLevel } from 'net-client'

setDebug(true)                     // 一键打开全部模块调试日志
setLogLevel(LogLevel.WARN)         // 精细控制
setLogTransport((level, scope, args) => reportToServer(level, scope, args))

开发与验证

npm install

npm run typecheck   # 类型检查（含类型冒烟测试）
npm run test        # 运行时冒烟测试（注入假 uni 运行时，56 条断言）
npm run build       # 产出 dist/ + .d.ts
npm run verify      # 以上三步串起来跑

仓库里有两类测试，职责不同：

跑测试不需要任何测试框架和额外依赖，只依赖 typescript 一个 devDependency。

FAQ

Q：小程序里 SSE 收到的中文是乱码？ A：本库内置流式 UTF-8 解码器，会把被 chunk 截断的多字节序列暂存到下一块，不会出现乱码。若你自行处理 chunk 事件，请直接用 ev.json / ev.data，不要对 ArrayBuffer 逐块 String.fromCharCode。

Q：WebSocket 明明"连着"，但服务端收不到消息？ A：典型的假死连接。把 heartbeat.timeout 调小（如 8000），pong 超时会主动断开并触发重连。

Q：并发请求同时 401，会刷新很多次 Token 吗？ A：不会。AuthAdapter.refresh 有单飞保护，同一时刻只执行一次，其余请求等待同一个 Promise，成功后各自重放。

Q：H5 用 EventSource 不行吗？ A：EventSource 只支持 GET 且不能自定义请求头，无法携带 Authorization，所以默认走 fetch + ReadableStream；确有需要可 transport: 'eventsource'。

Q：包体积会不会很大？ A：核心库无任何运行时依赖，sideEffects: false 支持 Tree-shaking。MQTT 是可选 peerDependency，不用就完全不进包。

发布到 DCloud 插件市场

本仓库通过 scripts/sync-uni-module.js 把 src/ 同步进 uni_modules/net-client/， 该目录就是可直接发布的 uni_modules 插件包（已含 package.json / readme.md / changelog.md）。

插件目录结构：

uni_modules/net-client/
├── package.json      # uni_modules 描述文件（id / 平台 / 依赖）
├── readme.md         # 即本文档
├── changelog.md      # 版本更新日志
├── index.ts          # 统一导出入口（默认单例 net + 全部类型）
├── core/             # http / websocket / mqtt / sse / socket 实现
├── adapters/         # ws-polyfill 等平台垫片
├── shared/           # 事件 / 错误 / 日志 / 平台探测等基础能力
└── types/            # 全部对外 Interface 定义

提交方式（二选一）：

1. HBuilderX：右键 uni_modules/net-client 目录 → 「发布到插件市场」。
2. 插件市场网页：把 uni_modules/net-client 整目录压缩上传（解压后根目录应为 uni_modules/net-client/）。

可运行的示例工程在仓库的 demo/ 目录，可在插件市场「示例工程」处一并上传，方便用户一键导入体验。

License

MIT