1. 为什么是 EMQX 配 MQTTX——先想清楚这套组合解决什么问题接触物联网消息通信的人几乎绕不开“MQTT”三个字。MQTT 是一种基于发布/订阅模式的消息协议它和 HTTP 那种“请求一次、响应一次”的模式完全不同消息的生产者发布端不直接发给消费者订阅端而是先发到一个中转站由中转站按主题路由给所有订阅了这个主题的人。这个中转站就是 MQTT Broker消息服务器。所以做 MQTT 开发你至少需要两样东西一个 Broker 负责收消息和转消息一个客户端工具负责发消息和收消息用来验证链路通不通。EMQX 和 MQTTX 正好就是这套组合里最有代表性的两个成员。EMQX 是开源的高性能 MQTT Broker底层由 Erlang 编写单机就能扛住海量连接在物联网、车联网、移动推送这些场景里非常常见MQTTX 是同一个团队出品的跨平台客户端调试工具界面化操作不需要写代码就能模拟设备发消息、收消息对新手极其友好。你可以把它们理解成“QQ 聊天室”EMQX 是服务器负责把某个房间里的人拉进群、转发消息MQTTX 是其中一部手机登录后可以进任意房间发言也可以听别人发言。这个教程就是写给想在 Windows 10 上折腾这套环境的人。不管你是打算做毕设、搭一个本地智能家居演示还是刚进公司需要在本机模一套 IoT 通信环境都可以照着下面的顺序操作。全文以 Windows 10 作为演示系统从 EMQX 下载安装、后台配置、MQTTX 连接到完整跑通一次发布/订阅消息链路最后补上我在 Windows 上踩过的一些坑和排查思路。我见过不少朋友一开始直接去看 Linux 部署文档搞得挺痛苦。其实在 Windows 10 上做开发调试有一个巨大优势Dashboard 和客户端都在同一个可视图形环境里消息跑没跑通、哪一步报错一眼就能看到。先把本机链路跑明白再去理解 Linux 部署或者集群会顺手很多。2. EMQX 的获取与安装先选对发行包再决定用哪种启动方式2.1 下载什么版本ZIP 包还是安装程序EMQX 官网的下载页面提供多个版本社区版Community完全免费对个人学习和大多数中型项目已经绰绰有余。Windows 平台下的文件目前主要是 ZIP 压缩包形式部分版本也提供 MSI 安装程序。我的建议是如果只是为了本机调试优先选 ZIP 包理由很简单不需要写注册表不影响系统现有软件想换版本时直接删文件夹就能清理干净。如果后面想把 EMQX 注册成 Windows 服务让电脑开机自启再考虑用安装程序。下载时注意 CPU 架构现在是 Windows 10 基本都是 x86_64选 amd64 后缀的包就好。另外我会顺手把 MQTTX 的安装包也下载下来后面不用来回切页面。2.2 解压目录的标准避免中文路径和空格ZIP 包下载完成后解压时有一个非常容易被忽略的细节路径中不要有中文也不要有空格。比如解压到“C:\Program Files\emqx”或者“D:\软件\emqx”都有概率导致 Erlang 节点启动失败或出现奇怪的乱码日志。最保守的做法是放在磁盘根目录下的纯英文目录比如D:\emqx或C:\emqx。解压后目录结构大致是这样emqx ├── bin # 启动、停止、控制台等命令行工具 ├── etc # 配置文件emqx.conf、auth、listeners 等 ├── data # 运行数据、持久化消息 ├── log # 运行日志 ├── plugins # 插件目录 └── lib # 依赖库确认目录没问题后接下来最核心的就是启动方式的选择。这一步很多新手会卡住因为 EMQX 在 Windows 上启动的方式和你在网上搜到的 Linux 文档写的不太一样。2.3 用 emqx.cmd 控制启动控制台模式与后台模式的区别打开 PowerShell 或 CMD先进入 EMQX 的 bin 目录cd /d D:\emqx\bin然后你会看到emqx.cmd这个脚本文件。注意不是直接执行emqxWindows 下要靠这个.cmd文件来包装原生命令。启动方式有几种最简单的是前台控制台模式emqx.cmd console执行后Erlang 虚拟机开始加载窗口里会连续输出日志能看到类似 “EMQX 5.x is started successfully!” 的信息。这个模式的好处是日志实时滚动如果启动过程出错错误信息会直接打在眼前非常适合第一次部署时排错。它的缺点也明显当前窗口不能关闭一关闭 EMQX 进程也跟着退出。另一种是后台模式emqx.cmd start这个命令执行后窗口会很快回到提示符EMQX 在后台运行你继续用这个终端窗口干别的活不会影响它。查看状态用emqx.cmd status停止服务用emqx.cmd stop我在第一次启动时总是习惯先跑一遍console确认所有日志正常再用start正式后台运行。如果console模式能正常输出启动成功但start模式启动后立刻又停掉了绝大多数情况是环境变量或目录权限有问题稍后我单独讲排查链路。除了这两种方式还可以用 MSI 安装包装完直接注册成 Windows 服务在服务管理器里看到 “EMQX” 服务支持开机自启。这样更适合长期运行的场景比如你想让本机扮演一个正式的局域网 Broker 角色。优先建议先跑通 console再决定要不要做成服务别一上来就服务化调试时看日志很麻烦。启动完成后打开浏览器输入http://localhost:18083如果能看到 EMQX 的 Dashboard 登录页面说明 Broker 已经活了。18083 是 Web 控制台默认端口1883 是 MQTT 协议默认端口这两个端口是我们后面主要打交道的对象。3. EMQX 初始配置登录后台、改密码、控端口、放行防火墙3.1 Dashboard 首次登录默认账号和密码一定要改EMQX 的 Dashboard 首次登录使用的默认账号是admin默认密码是public。输入后系统会进入一个引导流程要求你重新设置管理密码。这里千万别跳过因为 Dashboard 拥有 Broker 的完整管理权限包括查看所有客户端的订阅关系、修改认证规则甚至可能影响消息流转。保留默认密码等于把服务器大门钥匙挂在门口。新版 Dashboard 界面整体分成几个区域概览、连接管理、主题管理、订阅管理、诊断、配置、监控等。刚开始不需要把每个菜单都摸透重点看三块左侧菜单里的“连接”能实时看到当前连上了多少个客户端每个客户端的 Client ID、IP、协议版本、状态这对后面验证 MQTTX 是否真的连上来很有用。“主题”展示 Broker 感知到的主题列表和消息数量能辅助理解消息路由。“配置”这里可以调整包括监听端口、消息保留策略、认证机制在内的核心参数。3.2 端口约定1883 干活18083 管人8081 是 APIEMQX 默认开启的监听端口里常用端口这样记忆端口协议用途什么时候用1883MQTT over TCP最常见的 MQTT 设备接入端口8883MQTT over TLS需要加密传输时使用8083MQTT over WebSocket浏览器或集成 WebSocket 的客户端8084MQTT over WSS加密的 WebSocket8081HTTP API用程序调用管理接口18083Dashboard 管理后台浏览器访问控制台默认情况下本机调试只需要 1883 和 18083 两个端口。如果你是默认解压、默认启动不需要手动改配置。但如果你本机 1883 或 18083 端口被别的程序占用了那就要去etc/emqx.conf里找到监听器相关配置手动调整。这里有一个关键知识点EMQX 5.x 版本把端口设置组织成“监听器listener”的概念每个监听器绑定一个协议、一个 IP 地址和一个端口。修改后必须重启 EMQX 才生效。修改配置文件之前先备份一份原文件永远是好习惯。用emqx.cmd stop停掉服务改完emqx.cmd start重启整个过程不需要重装。3.3 Windows 防火墙最容易被忽视的隐形拦截者我在本地测试时曾遇到过这样的怪现象在 EMQX 所在的同一台电脑上MQTTX 能正常连接 1883 端口但局域网里另一台电脑或手机上的 MQTT 客户端怎么都连不上一直报超时。查了半天问题往往出在 Windows 防火墙没有放行 1883 和 18083 端口。Windows 防火墙默认行为会比较保守当你第一次启动 EMQX 这样的进程时屏幕上会弹出“是否允许此应用访问网络”的提示框。很多人会下意识点“取消”结果后续所有外部访问全被拦截。如果你已经错过弹窗提示可以手动放行打开“控制面板 - Windows Defender 防火墙 - 高级设置”在左侧选择“入站规则”然后在右侧点击“新建规则”选择“端口”协议选 TCP端口范围填1883, 18083用逗号隔开多个端口然后选择“允许连接”勾选所有网络类型最后命名并完成。如果只是自己本机测试这一步其实不是必须的但只要你有任何“手机通过局域网连接电脑上的 EMQX”这种需求防火墙的坑就会冒出来。做完放行后再结合后面的 MQTTX 连接就会很顺畅。4. MQTTX 的安装与环境准备这个客户端比你想的更好用4.1 下载安装两种形式随你选MQTTX 是跨平台的桌面应用官网有 Windows 安装包也可以在 GitHub Releases 里找到便携版。我的习惯是下载便携版解压后直接运行因为它把配置和程序放在一起换机器方便。如果你平时习惯安装软件用安装包就行两者功能没有区别。打开 MQTTX 后界面是典型的左侧列表区加中间对话操作区。第一次打开可能有点空因为还没有任何连接配置。左侧最上方有一个“新建连接”按钮点进去就是核心配置表单。4.2 创建连接配置各字段逐一说明这一步是整个教程里信息密度最高的环节很多初学者失败不是因为 EMQX 没装好而是不知道连接表单里的字段该填什么。表单里的核心字段如下名称这个连接在 MQTTX 里的显示名随便填比如“本地 EMQX 测试”。它就是让你分辨不同连接的标签。Client ID客户端的唯一标识默认会生成一个随机字符串形如mqttx_xxxxxx。需要注意同一个 Client ID 同时只能有一个客户端在线如果两台设备用相同的 Client ID 接入先连上的那台会被 Broker 踢下线。本机测试时直接用默认随机值即可不用动。Host 地址这里默认是mqtt://localhost:1883。协议头会自动根据你填的内容变化支持mqtt://、mqtts://、ws://、wss://四种。连接本地 EMQX 时保持mqtt://localhost:1883。用户名、密码如果 EMQX 没有开启认证这两个字段可以留空要是开启认证必须填写之前创建的用户名密码否则连接会被拒绝。这里需要提醒一下EMQX 5.x 默认允许匿名访问所以留空也能连上。但只要你通过 Dashboard 给“认证”模块添加了任意一个用户匿名策略就会发生变化未带账号的连接会直接失败这个坑会在后面的排查章节详细说。Keep Alive保活时间默认 60 秒表示客户端每隔 60 秒发一个心跳包告诉 Broker“我还活着”。如果你的网络环境不稳定可以适当调短比如 30 秒但调太短会频繁发无效包浪费流量和性能一般不轻易动它。Clean Session清理会话决定连接断开后Broker 是否保留该客户端的会话状态。日常测试勾选“自动开启”即可这样每次重连都是一次全新的会话不会出现订阅关系残留导致消息重复收的怪现象。SSL/TLS默认关闭。本地测试完全不需要开只有连 8883 或 8084 端口时才需要打开并配置证书。这些字段理解清楚后回到填写本身输入名称、host 中填mqtt://localhost:1883其他保持默认然后点击右上角“连接”按钮。连接成功后界面会有一个明显的状态变化连接列表里的条目旁边出现绿色小圆点中间的消息编辑区从灰色变成可用状态。到这里EMQX 和 MQTTX 的安装、连接环节就算彻底打通了。如果弹窗报“连接超时”或“连接被拒绝”先别急着怀疑 EMQX 坏了百分之八九十的问题是端口没起来或者防火墙拦截具体排查思路我会单独立一节。5. 发布与订阅完整跑通一次消息流动链路5.1 单客户端自测先在同一个连接里订阅并发送连接建立后MQTTX 中间区域上方是消息操作栏下面是消息历史区。第一次做链路验证时我建议用一个连接就完成最基础的前后闭环。具体操作在“订阅主题”输入框填入test/topic点击订阅按钮订阅成功后该主题会出现在左侧订阅列表里。然后在发送区把主题同样填成test/topicpayload 填写hello from mqttx点击发送按钮。重点来了因为你在同一个连接里既订阅了这个主题又发布了同名主题MQTT 的发布/订阅机制会把你发出去的消息也路由回给你自己所以消息历史区会立刻多出一条“入站”记录内容就是刚才发送的 payload。这个简短循环能直接证明 Broker 的转发功能工作正常。5.2 双客户端验证模拟真实设备间通信单连接自测通过后我们再模拟更接近真实场景的设备间通信一台设备发另一台设备收。在 MQTTX 里点左上角再新建一个连接。顺手把第二个连接的 Client ID 改成容易识别的字符比如client-BHost 还是mqtt://localhost:1883然后连接。现在两个连接都连到本地 EMQX 上了你可以给连接 A 订阅device/data主题然后连接 B 向device/data发送一段 JSON 数据{deviceId:device-001,temperature:26.5,humidity:60}连接 A 的消息历史区应该立刻出现这条消息并且 payload 里能看到我刚才写的设备信息。这样一个“设备上报数据服务端接收”的完整链路就通了。反过来服务端向设备下发的指令也是一样的逻辑只是主题和方向换一下比如用device/001/control下发{switch:off}。这里顺便提一个理解 MQTT 消息路由的常见误区MQTT 的订阅关系是按“主题”匹配的并不是按“连接”匹配的。也就是说即使连接 A 和连接 B 的 Client ID 完全不同只要订阅的是同一个主题Broker 就会把消息复制给所有订阅者这正是 MQTT 天然支持多设备广播的原因。5.3 Dashboard 视角实时观察连接和消息此时打开 EMQX 的 Dashboard切到“连接管理”页面你能看到 MQTTX 的两个连接都在线各自的 Client ID、远端 IP、协议版本一目了然。切到“主题”或“订阅”页面能看到test/topic和device/data这些主题出现在列表中消息计数也在跳动。我强烈建议初学者在验证时保持 Dashboard 和 MQTTX 同屏可见因为这种“一端发送、一端接收、后台同步显示”的体验能把 MQTT 的整个消息模型在脑子里钉死。很多人学了几个月协议概念都还是抽象理解不如实际跑 5 分钟印象深刻。5.4 通配符为什么和#非常重要做真实项目时设备主题往往是有层级的比如devices/esp32-001/temperature、devices/esp32-001/humidity。你当然可以一条一条去订阅完整主题但 MQTT 提供了通配符机制匹配单层订阅devices//temperature能收到devices/esp32-001/temperature和devices/esp32-002/temperature但收不到devices/esp32-001/humidity。#匹配多层订阅devices/#能收到devices/下面所有级层的所有消息。在 MQTTX 里你可以直接创建一个订阅主题写devices/#然后从另一个连接向devices/esp32-001/temperature发一条消息观察通配符订阅是否收到。这一步做完你对主题树的理解基本就到位了。6. Windows 环境下的高频踩坑与排查链路我遇到过的都在这了6.1 启动时报错不是内部或外部命令最常见的启动失败其实是命令都没找对。很多人下载完 EMQX 后直接在 PowerShell 的任意目录里输入emqx start然后系统提示“不是内部或外部命令”。这不怪 EMQX而是当前目录不在命令搜索路径里。解决方式有两种一种是先cd进入 bin 目录再执行另一种是把 bin 目录加入环境变量 PATH。set PATH%PATH%;D:\emqx\bin这种设置只对当前终端窗口生效重启终端后需要重新设置。如果要永久生效去“系统属性 - 环境变量”里把 bin 路径追加到 PATH 中。6.2 端口被占用1883 和 18083 起不来emqx.cmd start执行后没有任何报错但浏览器打不开 18083或者 MQTTX 连 1883 失败这种情况我见过很多次原因经常是端口被别的程序占用。Windows 下确认端口占用和进程的命令是netstat -ano | findstr :1883看到类似TCP 0.0.0.0:1883 LISTENING 10086的输出后面的数字就是占用进程的 PID。再用tasklist | findstr 10086查出来是哪个进程。如果是残余的 EMQX 进程可以杀掉后重新启动如果是其他程序占了端口要么关掉那个软件要么按前面说的修改 EMQX 监听端口。6.3 Erlang 节点的 cookie 冲突还有一种启动后状态异常的情况你之前在同一台机器上装过别的 Erlang 应用或旧版 EMQX启动时日志里出现 cookie 相关的报错比如 “Accept cookie failed” 或节点名冲突。Erlang 节点之间通信依赖一个叫 cookie 的校验字符串多套 Erlang 应用并存时cookie 不一致就会出现互相不认的情况。处理办法不复杂进入 EMQX 安装目录下的etc文件夹找到配置文件把 cookie 改成一段随机字符串比如myemqxsecretcookie2024同时注意这个值在所有 EMQX 节点上要一致如果是单机单实例随便填一串复杂度足够的内容就行。改完重启 EMQX问题会消失。6.4 防火墙放行之后仍然连不上有一种比较隐蔽的情况防火墙规则已经放行但局域网客户端还是连不上 1883 端口。这时要检查 EMQX 的监听器绑定地址。默认情况下监听器绑定的是0.0.0.0也就是所有网络接口一般没问题。但如果配置文件里手动改成了127.0.0.1外部流量就永远进不来。确认方式是在 Dashboard 的“配置”页面或直接查看emqx.conf里监听器的 bind 参数。记得本机测试无所谓想被局域网设备访问就确保绑定的是0.0.0.0。6.5 MQTTX 提示 Unauthorized 或 Connection refused连接时如果提示 “Unauthorized”最可能的原因是 EMQX 5.x 的认证机制虽然默认匿名访问是允许的但你在 Dashboard 的“认证”模块里添加过一个用户后策略就会收紧MQTTX 必须填写正确的用户名和密码才能接入。另一层可能是密码确实填错。解决办法是回 Dashboard 的“认证”模块确认当前的认证配置看看是内置数据库认证还是 HTTP 外部认证然后按实际情况调整 MQTTX 的账号信息。“Connection refused”则一般是服务没起来、端口没监听或者客户端访问了错误的地址。先用emqx.cmd status确认 EMQX 进程状态再用netstat排查端口很多时候就是进程挂了没注意。6.6 路径中文目录引发的教训最后说一个我身边的人真实遇到过的坑把 EMQX 解压到D:\物联网项目\emqx下启动时 Erlang 的日志变得无法读取有时干脆起不来。换到纯英文目录后一切正常。这不是玄学是 Erlang 虚拟机对非 ASCII 字符路径的支持不够完善。建议任何从网上下载的服务端软件安装路径都遵循纯英文、无空格、不超过目录层级的原则。这不是 Windows 不行而是跨平台技术栈的兼容性问题遇见了才知道多扎心。7. 从本机测试走向真实场景认证、加密和扩展思路7.1 开启账号认证让陌生人连不上你的 Broker本机测试阶段不设账号密码无所谓可一旦 EMQX 部署到局域网服务器或者你按某些教程配置过端口转发那匿名访问就是巨大的风险敞口。任何人只要知道你的 IP 和端口无需密码就能订阅所有主题相当于站在你门口偷听。所以进入真实场景的第一步就是开启账号认证。在 EMQX Dashboard 的“认证”页面选择“内置数据库”添加一个或多个客户端用户名密码保存后重启或刷新匿名访问就被禁掉了。之后 MQTTX 再连接时“用户名”和“密码”两栏就必须填写刚才创建的内容。这时候你再看 Dashboard 的连接列表用的都是真实账号上来管理端能精确区分客户端身份审计和追踪也变得容易。内置数据库的认证方式适合设备量不大、业务简单的场景。等设备量上来、账号要求动态管理时再考虑 HTTP 认证或 JWT 等方式它们把账号校验逻辑外置到业务服务器Broker 自己的压力会小很多。不过这是后话今天不展开。7.2 让链路加密本地用 TLS 也值得学MQTT 默认走明文消息里的 payload 全部裸露在网络上。局域网内或许无所谓但跨公网传输时明文数据的风险比较大。EMQX 默认开启了 8883 端口用于 MQTT over TLS只是在本地调试时你还需要配置证书才能通信。最简单的本地测试方案是生成自签名证书然后在 EMQX 的 Dashboard 或配置文件中把证书路径指过去然后在 MQTTX 连接设置里打开 SSL/TLS 开关并选择“自签名证书”模式连接地址改为mqtts://localhost:8883。这样链路就加密了。很多人觉得本地测试没必要搞 TLS但我的观点是花半小时把自签名证书这套流程走一遍后面在真实环境里接 CA 证书时就非常顺畅因为在 MQTTX 里配置证书的入口、参数含义你都摸过一遍了。如果连自签名证书都不会配到了生产环境面对一整套证书体系会更混乱。作为学习路径这一步很值得。7.3 让浏览器也能接入WebSocket 端口的用处物联网场景里经常有网页实时监控页面的需求浏览器原生不直接支持 TCP 连接很多时候是通过 WebSocket 协议桥接 MQTT 消息。EMQX 默认监听 8083 端口MQTT over WebSocket在 MQTTX 里新建一个连接地址填ws://localhost:8083/mqtt注意 WebSocket 路径默认一般是/mqtt协议头一定不要写成mqtt://。配置好后MQTTX 依然可以订阅、发布功能表现和 TCP 一致。这个知识点在对接 Web 前端项目时特别重要。你先在 MQTTX 里验证 WebSocket 端口通不通然后再去写前端代码会省很多联调时间。7.4 向外延伸连接手机端或公有云平台时怎么调整思路MQTTX 有手机版安装后只要把 Host 地址从localhost改成电脑的局域网 IP并且确保防火墙已放行手机就能直接连上电脑上的 EMQX 进行收发测试。这个操作简单但意义重大它让你第一次在真实硬件设备上感受到 MQTT 的即时性和低流量优势。如果你想接入一些公有云物联网平台的 MQTT 服务逻辑也一样把 Host 地址改成平台分配的接入地址端口通常也是 1883用户名密码换成平台颁发的设备秘钥连接成功后所有消息就走云端的通道了。掌握了本地这套安装和调试方法后迁移到任何平台都只是改几个配置参数的事不需要推翻重来。总的来说EMQX 加 MQTTX 这套组合我觉得是所有 MQTT 学习路径里效率最高的一条线。它把“服务端”和“客户端”可视化地摆在同一个屏幕上从零到跑通链路只需要小半天。我始终建议初学者不要跳过 Dashboard 的每个菜单也不要害怕报错把排查链路按端口、进程、防火墙、认证这几个维度切分大部分问题都能在几分钟内定位。本机这套环境跑顺之后你再去看任何 IoT 项目都会多一份从容。