前言

MQTT（Message Queuing Telemetry Transport，消息队列遥测传输协议）是一种基于发布/订阅（Publish/Subscribe）模式的轻量级通信协议，协议开销小、功耗低，是物联网领域最常用的协议之一，也非常适合手机 App 与开发板、传感器等设备之间互发消息。

想要在鸿蒙应用中使用 MQTT，整体思路分两步：

1. 准备一台 MQTT 服务器（Broker）——本文使用 EMQX 平台的 Serverless 服务免费创建一台；
2. 鸿蒙应用作为 MQTT 客户端连上服务器——借助三方库 @ohos/mqtt 完成连接、订阅、收发消息。

下面是完整的实现过程。

一、在 EMQX 平台创建 MQTT 服务器

1.1 进入控制台，新建部署

打开 EMQX 官网，注册账号并登录，进入控制台。在 概览 页面可以看到平台提供的两类服务：

• EMQX Broker：面向海量 IoT 连接的可靠 MQTT 消息服务（负责"连接"）；

• EMQX Tables：用于 MQTT 数据存储的全托管时序数据库（负责"存储"）。

我们要创建的是 MQTT 服务器，因此点击 EMQX Broker 卡片上的 ＋新建 按钮。

1.2 选择 Serverless 版本并部署

进入"新建部署"页面后，共有三种版本可选：

版本	特点	适用场景
Serverless	全托管、可伸缩；最高 1000 同时在线连接；每月免费额度	学习、测试、小型项目（本文选择）
弹性专有版	独立 VPC、资源隔离；14 天免费试用后按小时计费	生产环境
BYOC	部署在自己的云账户中	企业定制

学习测试用途选 Serverless 即可，每月免费额度包括 100 万连接分钟、1 GB 流量、100 万规则动作数，把消费限额设为 0 就完全免费。

具体部署步骤：

1. 版本选择 Serverless；
2. 区域选择离自己近的城市（杭州 / 深圳）；
3. 消费限额保持默认 0（仅使用免费额度，不会产生费用）；
4. 勾选 “我已阅读并同意 EMQX Serverless 使用条款”；
5. 点击 立即部署。

⚠️ 注意：Serverless 版本只开放 8883（MQTT over TLS/SSL）和 8084（WebSocket over TLS/SSL）两个加密端口。如果需要使用 1883/8083 等非加密端口，则要使用付费的弹性专有版。

1.3 查看连接地址与端口

等待部署状态变为 运行中 后，进入该部署的 部署概览 页面，可以看到最关键的连接信息：

• 连接地址：形如 xxxxxxxx.ala.cn-hangzhou.emqxssl.cn 的域名，这是客户端连接服务器的入口地址，后面代码中 MQTT_URL 填的就是它；

• MQTT over TLS/SSL 端口：8883，这是 MQTT 客户端通过 TLS/SSL 加密方式连接服务器时使用的端口，保证数据传输的安全性；

• WebSocket over TLS/SSL 端口：8084，这是浏览器或 Web 应用通过 WebSocket 协议连接时使用的端口，适合前端页面直接收发 MQTT 消息的场景；

• CA 证书文件：可下载，用于客户端校验服务器身份，增强连接安全性。如果使用 enableServerCertAuth: false 跳过证书校验，则可以不下载该文件。

把连接地址和端口记下来，后面代码中 MQTT_URL 填的就是它们。另外，部署页面左侧的 客户端连接指引 提供了各种语言/平台的连接示例，包括 Java、Python、Node.js、鸿蒙等，遇到问题时可以参考官方示例快速排查。

💡 小提示：连接地址中的 xxxxxxxx 是每个部署实例独有的随机前缀，不同用户创建的部署地址各不相同。在后续编写鸿蒙代码时，需要将 MQTT_URL 替换为你自己部署实例的实际地址，并确保端口号与连接方式（TLS/SSL）匹配，否则会出现连接失败的问题。

1.4 添加客户端认证（用户名 / 密码）

EMQX 默认不允许匿名连接，所以还需要给服务器添加一组用于连接认证的用户名和密码。

操作路径：左侧菜单 访问控制 → 客户端认证，在"默认认证"页签中点击 ＋添加，在弹出的"添加认证"窗口中输入自定义的 用户名 和 密码，点击 确认，列表中出现该用户名即添加成功。

代码中的 USERNAME、PASSWORD 填的就是这里设置的内容。

到这里，EMQX 平台侧的 MQTT 服务器就搭建完成了。

二、在 DevEco Studio 安装 MQTT 三方库

鸿蒙原生 API 并没有内置 MQTT，需要通过 ohpm（OpenHarmony 包管理器）安装三方库 @ohos/mqtt。

打开 DevEco Studio 工程，点击编辑器底部的 终端（Terminal），执行：

ohpm install @ohos/mqtt

看到 install completed 提示即为安装成功。

三、鸿蒙 MQTT 客户端代码实现

说明：本节主要代码转载自其他博主的博客（原文地址：https://blog.csdn.net/whwdyx/article/details/160505994?fromshare=blogdetail&sharetype=blogdetail&sharerId=160505994&sharerefer=PC&sharesource=2201_75604869&sharefrom=from_link），本文进行了部分代码修改与补充说明，仅供学习交流，感谢原作者分享！

3.1 添加网络权限

MQTT 基于网络通信，需先在 entry/src/main/module.json5 的 module 下声明网络权限：

"requestPermissions":[
   {
      "name" : "ohos.permission.INTERNET",
   }
],

3.2 主要代码（Index.ets）

import { MqttAsync, MqttConnectOptions, MqttMessage, MQTT_SSL_VERSION } from '@ohos/mqtt';

const MQTT_URL = 'ssl://******a4.ala.cn-hangzhou.emqxsl.cn:8883'  // 自己的mqtt的访问地址（EMQX的连接地址，1.3的连接地址和端口）
const CLIENT_ID = 'BBB' // 客户端ID（随便取名，后续连接的需要使用,但别重复）
const TOPIC = 'testtopic/1'      // 订阅/发布需要的主题
const QOS = 1                   // 服务质量等级（0/1/2）
const USERNAME='***'             // 自己登录mqtt时要用的用户名//用户名（1.4创建的客户端）
const PASSWORD='******'  // 自己登录mqtt时要用的密码
@Entry
@Component
struct Index {
  @State msg: string = ""
  @State sendmsg: string = ""

  client = MqttAsync.createMqtt({   //创建异步客户端
    url: MQTT_URL,
    clientId: CLIENT_ID,
    persistenceType: 1  // 客户端持久化类型（0=文件系统，1=内存，2=自定义）
  })
  async mqttCommunication() { //异步连接客户端函数
    try {
      await this.client.connect({//异步访问mqtt地址
        cleanSession: true, // 清除会话（断开后不保留订阅和消息）
        connectTimeout: 30, // 连接超时时间（秒）
        keepAliveInterval: 60, // 心跳间隔（秒），维持长连接
        // 认证信息（若Broker需要）
        userName:USERNAME , // 自己登录mqtt时要用的用户名
        password: PASSWORD, // 自己登录mqtt时要用的密码
        sslOptions:
        {
          enableServerCertAuth: false,//关闭 TLS/SSL 连接中的服务器证书验证,仅在学习或测试时使用
        }
      });
      this.msg = 'mqtt： 连接成功'
      await this.client.subscribe({// 订阅主题
        topic: TOPIC,
        qos: QOS
      });
      this.msg += `已订阅主题：${TOPIC}（QoS： ${QOS}）`

    } catch (err) {
      this.msg += '\n操作失败:' + err.message
    }
    this.client.messageArrived((TOPIC,message:MqttMessage)=>{//消息到达监听器
      // 更新UI显示
      this.msg += `\n${message.topic}\n`;
      this.msg += `[接收消息] 内容：${message.payload}\n`;
    });
  }
  async sendMessage(message:string){//发送消息
    await this.client.publish({
      topic: TOPIC,
      payload: message,
      qos: QOS,
      retained: false, // 是否保留消息（Broker存储最后一条消息）
    });
  }

  build() {
    Column() {
      Button("连接mqtt").onClick(() => {
        this.mqttCommunication();
      })
      Text(this.msg).fontSize(26)
      TextArea({ text: this.msg }).fontSize(26).width("100%").height(550);
      Row() {
        Button("断开连接mqtt").onClick(() => {
          this.client.disconnect();
          this.msg = ""
        })
        Button("清屏").onClick(()=>{
          this.msg=""
        })
      }
      Text("请输入发送信息：").fontSize(26)
      TextInput({text: $$this.sendmsg}).fontSize(26)
      .onChange((value:string)=>{
        this.sendmsg=value
      })
      Button("发送").onClick(async ()=>{
        await this.sendMessage(`${CLIENT_ID}发送:`+this.sendmsg)
        this.sendmsg = ''
      })
    }
    .height('100%')
    .width('100%')
  }
}

3.3 代码要点解析

① 连接参数定义

常量	含义	说明
MQTT_URL	MQTT 服务器地址	换成 1.3 节拿到的地址 + 端口
CLIENT_ID	客户端 ID	需要唯一，重复会互相挤下线
TOPIC	主题	订阅、发布都围绕它进行
QOS	服务质量等级	0=至多一次；1=至少一次；2=恰好一次
USERNAME / PASSWORD	登录认证信息	1.4 节添加的用户名和密码

② 创建客户端：MqttAsync.createMqtt() 创建一个异步 MQTT 客户端；persistenceType 为客户端持久化类型（0=文件系统，1=内存，2=自定义），学习测试用 1 即可。

③ 连接与订阅：connect() 的常用参数——

• cleanSession: true：清除会话，断开后不保留订阅和消息；

• connectTimeout: 30：连接超时时间（秒）；

• keepAliveInterval: 60：心跳间隔（秒），用于维持长连接；

• userName / password：服务器的认证信息。

连接成功后紧接着调用 subscribe() 订阅主题。

④ 接收消息：messageArrived() 注册消息到达监听器，订阅的主题上一有新消息就会触发回调，从 message.topic 和 message.payload 中取出内容并更新到界面显示。

⑤ 发送消息：publish() 向主题发布消息；retained: false 表示不保留消息（为 true 时 Broker 会存储最后一条消息，新订阅者一连上就能收到）。

⑥ 界面：连接按钮、消息显示区（TextArea）、断开连接、清屏、输入框、发送按钮，方便完成收发自测。

3.4 注意事项（容易踩的坑）

1. 参数替换：MQTT_URL、USERNAME、PASSWORD 必须换成自己的信息；
2. 端口与加密：上面的代码使用 1883 端口（非加密），适用于自建 Broker；而 EMQX Serverless 只开放 8883 加密端口，因此连接 Serverless 服务器时，MQTT_URL 应写成类似 ssl://xxxxxxxx.ala.cn-hangzhou.emqxssl.cn:8883 的形式，TLS 相关配置（如 CA 证书）可参考 @ohos/mqtt 库的说明与 EMQX 的客户端连接指引；
3. CLIENT_ID 唯一性：多个客户端使用同一个 ID 会相互挤掉线。

四、运行测试

1. 替换好参数后，将应用运行到真机或模拟器上；
2. 点击 “连接 mqtt” 按钮，显示区出现"连接成功""已订阅主题"字样即连接成功（此时回到 EMQX 的部署概览页，也可以看到连接数的变化）；
3. 在输入框输入内容，点击 “发送”：消息会发布到 testtopic/1 主题；由于客户端自己也订阅了该主题，消息经服务器转发回来，显示区会出现 [接收消息] 内容：***发送:xxx——说明订阅、发布、接收整条链路都已打通。

五、总结

• 用 EMQX 平台 Serverless 版本可以免费创建一台 MQTT 服务器，注意它只开放 TLS 加密端口 8883/8084；

• 鸿蒙侧通过 ohpm install @ohos/mqtt 安装三方库，并记得在 module.json5 中添加 ohos.permission.INTERNET 网络权限；

• MQTT 客户端的核心流程只有四步：创建客户端 → 连接（认证）→ 订阅主题 → 发布 / 监听消息。