MQTT 模块

MQTT 模块为 XScript 提供 MQTT 协议支持,用于物联网设备间的轻量级消息传输。

🎉 mqtt.js 兼容性

本模块现已完全兼容 mqtt.js API,这意味着:

✅ 可以直接使用 mqtt.js 的代码示例

✅ 支持 EventEmitter 事件系统 (on/emit/once)

✅ 支持链式调用 (方法返回 client 对象)

✅ 完全相同的 API 签名和参数格式

✅ 向后兼容原有 XScript MQTT API

快速开始 (mqtt.js 风格)

支持的 mqtt.js 事件

事件	说明	参数
`connect`	连接成功	`(connack)`
`message`	收到消息	`(topic, message, packet)`
`error`	发生错误	`(error)`
`close`	连接关闭	`()`
`reconnect`	开始重连	`()`
`offline`	客户端离线	`()`
`end`	客户端结束	`()`

支持的 mqtt.js 方法

方法	说明
`mqtt.connect(url, options)`	连接到 MQTT broker
`client.publish(topic, message, [options], [callback])`	发布消息
`client.subscribe(topic, [options], [callback])`	订阅主题
`client.unsubscribe(topic, [options], [callback])`	取消订阅
`client.end([force], [options], [callback])`	断开连接
`client.reconnect()`	重新连接
`client.on(event, handler)`	添加事件监听器
`client.once(event, handler)`	添加一次性事件监听器
`client.removeListener(event, handler)`	移除事件监听器

URL 格式支持

功能特性

发布/订阅 - MQTT pub/sub 模式

QoS 支持 - 三种服务质量级别

持久会话 - 保持连接状态

遗嘱消息 - 异常断开通知

TLS/SSL - 安全连接支持

自动重连 - 断线自动重连

基本使用

引入模块

连接 MQTT 服务器

订阅主题

接收消息

发布消息

取消订阅

API 参考

连接方法

`mqtt.connect(url, options)`

连接 MQTT 服务器。

参数:

url (string) - MQTT 服务器地址

options (object) - 连接选项

clientId (string) - 客户端 ID

username (string) - 用户名

password (string) - 密码

keepalive (number) - 心跳间隔(秒)

clean (boolean) - 清除会话

订阅方法

`client.subscribe(topic, options)`

订阅主题。

参数:

topic (string|Array) - 主题

options.qos (number) - QoS 级别(0/1/2)

发布方法

`client.publish(topic, message, options)`

发布消息。

参数:

topic (string) - 主题

message (string|Buffer) - 消息内容

options (object) - 发布选项

qos (number) - QoS 级别

retain (boolean) - 是否保留消息

QoS 级别

级别	名称	说明
0	At most once	最多一次,可能丢失
1	At least once	至少一次,可能重复
2	Exactly once	恰好一次,最可靠

实际应用场景

智能家居控制

传感器数据采集

设备状态监控

最佳实践

选择合适的 QoS - 根据重要性选择

主题设计 - 使用层次化主题结构

保留消息 - 状态类消息使用保留

清理会话 - 临时客户端使用 clean session

错误处理 - 处理连接断开和重连

向后兼容性

为了保持向后兼容,原有的 XScript MQTT API 仍然可用。

原有 API (仍然支持)

API 对比

功能	mqtt.js 风格 (推荐)	原有风格 (兼容)
连接	`mqtt.connect(url, options)`	`mqtt.connectLegacy(name, config)`
发布	`client.publish(topic, msg, opts, cb)`	`mqtt.publish(name, topic, msg, qos, retain)`
订阅	`client.subscribe(topic, opts, cb)`	`mqtt.subscribe(name, topic, qos, callback)`
取消订阅	`client.unsubscribe(topic, opts, cb)`	`mqtt.unsubscribe(name, topic)`
断开	`client.end([force], [opts], [cb])`	`mqtt.close(name)`
事件	`client.on('event', handler)`	回调函数参数

迁移指南

如果您正在使用原有 API,建议迁移到 mqtt.js 风格的 API 以获得更好的兼容性和功能:

原有代码:

迁移后:

迁移优势:

✅ 与 mqtt.js 生态系统完全兼容

✅ 支持更丰富的事件系统

✅ 更好的错误处理

✅ 支持链式调用

✅ 更清晰的代码结构

参考资料

mqtt.js 官方文档

MQTT 协议规范

MQTT.js README

mqtt

MQTT 模块#

🎉 mqtt.js 兼容性#

快速开始 (mqtt.js 风格)#

支持的 mqtt.js 事件#

支持的 mqtt.js 方法#

URL 格式支持#

功能特性#

基本使用#

引入模块#

连接 MQTT 服务器#

订阅主题#

接收消息#

发布消息#

取消订阅#

API 参考#

连接方法#

mqtt.connect(url, options)#

订阅方法#

client.subscribe(topic, options)#

发布方法#

client.publish(topic, message, options)#

QoS 级别#

实际应用场景#

智能家居控制#

传感器数据采集#

设备状态监控#

最佳实践#

向后兼容性#

原有 API (仍然支持)#

API 对比#

迁移指南#

相关模块#

参考资料#

MQTT 模块

🎉 mqtt.js 兼容性

快速开始 (mqtt.js 风格)

支持的 mqtt.js 事件

支持的 mqtt.js 方法

URL 格式支持

功能特性

基本使用

引入模块

连接 MQTT 服务器

订阅主题

接收消息

发布消息

取消订阅

API 参考

连接方法

`mqtt.connect(url, options)`

订阅方法

`client.subscribe(topic, options)`

发布方法

`client.publish(topic, message, options)`

QoS 级别

实际应用场景

智能家居控制

传感器数据采集

设备状态监控

最佳实践

向后兼容性

原有 API (仍然支持)

API 对比

迁移指南

相关模块

参考资料