更新记录

1.0.16（2026-06-25）

修复ios编译错误

1.0.13（2026-06-25）

增加ssl 链接

1.0.12（2026-01-14）

优化

平台兼容性

uni-app(4.07)

uni-app x(4.07)

其他

xtf-mqtt

Android、iOS、鸿蒙 App 端 MQTT 连接插件，支持普通 TCP、SSL/TLS、CA 证书、p12/pfx 客户端证书、client.crt + client.key 分离式客户端证书。

支持平台

安装与运行

1. 下载插件到项目的 uni_modules/xtf-mqtt 目录。
2. 在页面或业务模块中引入 MqttControl。
3. Android/iOS 如使用原生依赖或三方 SDK，请制作并使用自定义基座。
4. 鸿蒙端建议将项目放在纯英文、无空格路径下运行，避免鸿蒙工具链路径限制。
5. 如果设备上安装过旧基座，建议先卸载旧基座后重新运行。

快速开始

import { MqttControl } from "@/uni_modules/xtf-mqtt"

const control: MqttControl = new MqttControl()

control.connect({
  host: "tcp://192.168.2.1:1883",
  clientId: "client_001",
  username: "admin",
  password: "password",
  cleanSession: true,
  automaticReconnect: true,
  keepAliveInterval: 60,
  connectionTimeout: 10,
  topic: ["demo/topic"] as string[],
  qos: [1] as number[],
  connectSuccess: function(res: boolean) {
    console.log("connectSuccess", res)
  },
  connectLost: function() {
    console.log("connectLost")
  },
  messageArrived: function(topic: string, msg: string) {
    console.log("messageArrived", topic, msg)
  },
  deliveryComplete: function() {
    console.log("deliveryComplete")
  }
})

SSL/TLS 连接

把 host 从 tcp://host:port 改为 ssl://host:port 即可启用 App 原生端 SSL/TLS 连接。

control.connect({
  host: "ssl://mqtt.example.com:8883",
  sslProtocol: "TLSv1.2",
  sslInsecure: false,
  clientId: "client_ssl_001",
  username: "admin",
  password: "password",
  cleanSession: true,
  automaticReconnect: true,
  connectSuccess: function(res: boolean) {
    console.log("ssl connect", res)
  }
})

单向证书认证

只需要校验服务端证书时，传入 CA 证书文件路径 sslCaCertPath。

control.connect({
  host: "ssl://mqtt.example.com:8883",
  sslProtocol: "TLSv1.2",
  sslInsecure: false,
  sslCaCertPath: "/static/certs/ca.crt",
  clientId: "client_ca_001"
})

双向证书认证 p12/pfx

三端都支持 p12/pfx 客户端证书。该方式兼容性最好，推荐优先使用。

control.connect({
  host: "ssl://mqtt.example.com:8883",
  sslProtocol: "TLSv1.2",
  sslInsecure: false,
  sslCaCertPath: "/static/certs/ca.crt",
  sslClientCertPath: "/static/certs/client.p12",
  sslClientKeyPassword: "123456",
  clientId: "client_p12_001"
})

双向证书认证 client.crt + client.key

三端字段保持一致，支持通过 sslClientCertPath 和 sslClientKeyPath 传入分离式客户端证书和私钥。

control.connect({
  host: "ssl://mqtt.example.com:8883",
  sslProtocol: "TLSv1.2",
  sslInsecure: false,
  sslCaCertPath: "/static/certs/ca.crt",
  sslClientCertPath: "/static/certs/client.crt",
  sslClientKeyPath: "/static/certs/client.key",
  clientId: "client_key_001"
})

证书文件路径

• 推荐把证书放到项目 static/certs/ 目录，例如 /static/certs/ca.crt、/static/certs/client.p12。
• Android、iOS、鸿蒙会自动把 /static/... 这类代码包文件转换为当前平台可读取的原生路径。
• 如果证书是运行时下载的文件，请传入 App 可访问的本地文件路径。
• 正式环境建议使用完整可信证书链，并保持 sslInsecure: false。

私钥格式说明

client.key 建议使用未加密 RSA PEM 私钥。若私钥已加密，建议先转换为 client.p12 或 client.pfx 后使用。

API

connect(opt)

连接 MQTT 服务器。

control.connect(opt)

subscribe(topic, qos, callback)

订阅一个或多个主题。

control.subscribe(["demo/topic"] as string[], [1] as number[], function(res: boolean) {
  console.log("subscribe", res)
})

unsubscribe(topic, callback)

取消订阅指定主题。

control.unsubscribe("demo/topic", function(res: boolean) {
  console.log("unsubscribe", res)
})

publish(topic, msg, qos, retained)

发布消息。

control.publish("demo/topic", "hello", 1, false)

isConnected()

获取当前连接状态。

const connected = control.isConnected()

disconnect()

断开 MQTT 连接。

control.disconnect()

MqttOpt 参数

注意事项

• 本插件当前仅支持 Android、iOS、鸿蒙 App 端，不再提供 Web/H5 实现。
• 使用 SSL 时，host 必须使用 ssl:// 协议头。
• 使用自签名证书时，推荐传入 sslCaCertPath，不要在正式环境使用 sslInsecure: true。
• Android/iOS 原生依赖和三方 SDK 需要自定义基座才能完整生效。
• 鸿蒙端建议使用纯英文、无空格项目路径，避免工具链构建失败。
• 三端双向认证优先推荐 p12/pfx，如需分离证书再使用 client.crt + client.key。

常见问题

为什么 Web/H5 不能用了？

浏览器不能直接连接原始 MQTT TCP/SSL 地址，只能使用 MQTT over WebSocket。本插件当前目标是 App 原生 MQTT 能力，因此已移除 Web 端。

sslInsecure 应该什么时候使用？

仅建议在测试环境临时使用，例如服务端使用自签名证书且暂时没有配置 CA 文件。正式环境应保持 sslInsecure: false 并传入可信 CA 证书或使用系统可信证书链。

双向认证推荐哪种证书格式？

推荐优先使用 client.p12 或 client.pfx，三端一致性最好。如果服务端证书体系要求分离文件，可以使用 client.crt + client.key。

开发文档

• UTS 语法
• UTS API 插件
• UTS 组件插件
• Hello UTS