MQTTX保姆级安装与使用教程：从下载到发布/订阅全流程

MQTTX保姆级安装与使用教程：从下载到发布/订阅全流程

本文以 Windows 11 为例，macOS 与 Linux 的安装步骤基本一致。全文约 5 分钟可以读完，跟着操作即可完成 MQTTX 的安装、连接公共测试服务器、发布与订阅消息的完整流程。

项目	说明
工具名称	MQTTX
适用人群	物联网初学者、嵌入式开发者、需要调试 MQTT 消息的工程师
难度	入门
运行环境	Windows / macOS / Linux
测试服务器	broker.emqx.io（EMQX 官方公共测试服务器）

目录

1. MQTT 与 MQTTX 简介
2. 下载 MQTTX
3. 安装 MQTTX
4. 界面初识
5. 连接公共测试服务器
6. 发布消息
7. 订阅消息
8. 断开连接
9. 注意事项
10. 进阶使用建议
11. 常见问题 FAQ
12. 参考资料

一、MQTT 与 MQTTX 简介

MQTT（Message Queuing Telemetry Transport，消息队列遥测传输） 是一种基于发布/订阅（Publish/Subscribe）模式的轻量级物联网通信协议。它运行在 TCP 之上，报文体积小、带宽占用低、支持断线重连，非常适合智能家居、传感器数据采集、工业控制、车联网等场景。

MQTT 通信中有三个核心角色：

角色	作用
Broker（代理/服务器）	负责接收消息并转发给订阅者，相当于消息中转站
Publisher（发布者）	向某个主题（Topic）发布消息
Subscriber（订阅者）	订阅主题并接收该主题下的消息

MQTTX 是 EMQX 团队开发的一款跨平台 MQTT 桌面客户端，界面简洁、开箱即用，支持：

• MQTT 3.1.1 与 MQTT 5.0 协议
• TCP、WebSocket 等多种连接方式
• QoS 0/1/2 三种消息服务质量
• Text、JSON、Hex、Base64 等多种 Payload 格式
• 多连接管理、消息记录、脚本测试等实用功能

对初学者来说，MQTTX 最大的价值是：不需要写任何代码，就能直观地验证 MQTT 的发布/订阅流程，也可以作为日常开发调试的得力工具。

二、下载 MQTTX

2.1 进入官方网站

打开 MQTTX 官网：https://mqttx.app/zh/

在首页找到“下载”或“Download”按钮并点击。

也可以从 MQTTX 的 GitHub Releases 页面下载：https://github.com/emqx/MQTTX/releases

2.2 选择对应系统版本

官网会自动识别你的操作系统，也可以手动选择版本：

• Windows：下载 .exe 安装包，也可选择 .msi 安装包
• macOS：下载 .dmg 安装包
• Linux：下载 AppImage / deb / rpm 等格式
• 通用版（Universal）：适合大多数环境，示例中选用的是通用版

三、安装 MQTTX

3.1 双击安装包

下载完成后，双击安装包，进入安装向导。

3.2 选择安装方式

推荐选择“仅为我安装”（Install for me only），不需要管理员权限，安装更顺畅；如果这台电脑有多个用户都要使用，可以改为“为所有用户安装”。

3.3 选择安装目录

默认安装在当前用户的 AppData 目录下。如果想自定义安装位置，点击“浏览”选择其他目录，然后点击“安装”。

注意：安装路径尽量不要放在系统盘根目录或需要管理员权限的目录，否则后续可能出现权限不足的问题。

3.4 完成安装

等待安装进度条走完，点击“完成”即可。安装成功后，桌面会出现 MQTTX 快捷方式，也可以从开始菜单搜索并启动。

四、界面初识

首次启动 MQTTX 后，主界面主要包含以下几个区域：

区域	功能
左侧菜单栏	管理连接，点击“+”新建连接
连接列表	显示已保存的所有连接
中间消息区	展示当前连接的收发消息记录
右下角输入区	输入 Topic、Payload 并发送消息

五、连接公共测试服务器

在 MQTT 中，Broker 就是消息服务器。本教程使用 EMQX 官方提供的公共测试服务器 broker.emqx.io，它免费开放，支持 MQTT 3.1.1 与 5.0，适合学习和功能验证。

常用端口：

端口	用途
1883	TCP 明文连接
8883	TLS 加密连接
8083	WebSocket 连接
8084	WebSocket over TLS（WSS）连接

5.1 新建连接

点击左侧菜单栏的加号（+），打开“新建连接”配置界面。

5.2 填写连接参数

按下面的参数填写：

配置项	填写内容	说明
Name	test-demo	连接名称，方便自己识别，可以随意命名
Client ID	点击循环图标刷新生成	客户端唯一标识，同一服务器上不能重复
Host	broker.emqx.io	服务器地址
Port	1883	端口号
Username	留空	公共测试服务器无需用户名
Password	留空	公共测试服务器无需密码
SSL/TLS	关闭	测试环境可关闭；生产环境建议开启

提示：Client ID 后面的循环箭头图标用于随机刷新 Client ID。如果提示 Client ID 冲突，点击刷新重新生成即可。

5.3 点击 Connect

参数填写完成后，点击右上角的绿色 Connect 按钮。连接成功后，界面会显示 Connected，表示已成功连上公共测试服务器。

六、发布消息

6.1 填写Topic与消息内容

在右下角的输入区域：

1. Topic输入：test/demo1
2. msg后面的双引号内输入要发送的内容，例如：你好，MQTTX！
3. QoS保持默认的 0 即可

6.2 点击发送

点击右下角的发送按钮，消息会立即发布到test/demo1这个主题，界面中会出现一条发送记录。

说明：QoS 0 表示“最多一次”，消息可能丢失但性能最高；QoS 1 表示“至少一次”；QoS 2 表示“恰好一次”。公共测试服务器三种 QoS 都支持，日常学习用 QoS 0 即可。

七、订阅消息

订阅消息是MQTT的核心操作。只有订阅了某个主题，才能收到发布到该主题的消息。

7.1 新建订阅

在主界面点击New Subscription（新建订阅）。

7.2 输入订阅主题

在弹出的对话框中输入需要订阅的主题。这里订阅刚才发布的主题test/demo1，QoS保持默认，然后点击Confirm确认。

7.3 验证收发消息

订阅成功后，再次点击发送按钮发布一条消息，右侧图形区域就会显示接收到的消息。这说明发布与订阅流程已经全部打通。

八、断开连接

测试完成后，点击右上角的红色电源图标即可断开连接。断开成功后，界面会显示 Disconnected。

至此，恭喜你已经完成了MQTTX的安装、连接、发布、订阅和断开连接的完整操作流程。

九、注意事项

1. broker.emqx.io 只是公共测试服务器，仅供学习调试使用，正式项目千万不要用它。
2. 公共服务器上的数据是公开的，任何人都可能订阅同一主题，不要发送敏感信息。
3. 公共服务器不会对消息做持久化保障，服务可能重启、限流，不适合作为业务基础设施。
4. 端口 1883 是明文传输，涉及真实业务数据时请使用TLS加密端口8883。
5. Client ID在同一个Broker上必须唯一，否则可能导致连接互相挤掉线。
6. 正式项目中建议自建本地EMQX / Docker-EMQX服务，或使用云厂商的MQTT服务。

十、进阶使用建议

10.1 主题通配符

MQTT 主题支持通配符订阅：

通配符	含义	示例
+	匹配单层主题	test/+ 可匹配 test/demo1，不能匹配 test/a/b
#	匹配多层主题	test/# 可匹配 test/a、test/a/b 等

可以在MQTTX的New Subscription中直接体验通配符效果。

10.2 保留消息（Retain）

发布消息时勾选 Retain，Broker会保留该主题的最后一条消息。新的订阅者订阅该主题时，会立即收到这条保留消息，适合设备状态、配置信息等场景。

10.3 使用 Docker 自建 EMQX

本机安装 Docker 后，一条命令即可启动本地 EMQX：

docker run -d --name emqx -p 1883:1883 -p 8883:8883 -p 8083:8083 -p 8084:8084 -p 18083:18083 emqx/emqx:latest

启动后：

• MQTT 端口：1883
• WebSocket 端口：8083
• 控制台地址：http://localhost:18083
• 控制台默认账号：admin，默认密码：public

然后就可以在MQTTX中把 Host 填成localhost，体验自己搭建的Broker。

10.4 生产环境选型

如果不想自己维护服务器，也可以选择商业MQTT云服务，例如EMQX Cloud、阿里云微消息队列MQTT版等，通常提供完整的控制台、告警和权限管理能力。

十一、常见问题 FAQ

Q1：官网或 GitHub 下载很慢怎么办？

可以更换网络环境，或从镜像站下载；GitHub Releases页面有时需要代理才能稳定访问。

Q2：安装时被杀毒软件拦截怎么办？

MQTTX 是开源软件，可以放心使用。如果被杀毒软件误报，选择“信任该程序”后重新安装即可。

Q3：点击Connect后一直连接不上broker.emqx.io？

先检查网络是否正常，再确认Host和Port是否正确；如果网络环境限制较多，可以尝试8883（TLS）端口，或换一个网络测试。

Q4：已经 Connected，为什么收不到消息？

检查发布和订阅的主题是否完全一致；确认订阅动作是否成功；如果启用了消息过滤，请检查过滤条件。另外注意通配符 # 与 + 的用法。

Q5：提示 Client ID 冲突怎么办？

点击Client ID旁边的循环刷新图标，重新生成一个随机Client ID再连接。

Q6：中文内容显示乱码怎么办？

确认Payload格式选择的是Text，且编辑器编码为UTF-8。MQTTX 默认支持UTF-8中文消息。

Q7：能不能用 MQTTX 连接自己电脑上的 EMQX？

可以。把 Host 填成 localhost（本机部署）或局域网 IP，Port 填成 Broker 实际监听端口即可；跨设备连接时注意防火墙和端口放行。

十二、参考资料

• MQTTX 官网：https://mqttx.app/zh/
• MQTTX 使用文档：https://mqttx.app/zh/docs
• MQTTX GitHub 仓库：https://github.com/emqx/MQTTX
• EMQX 官网：https://www.emqx.io/zh
• MQTT 协议官方网站：https://mqtt.org/

---