一、下载并安装 EMQX 服务器
1.1 下载 EMQX Windows 版本
访问官方文档页面获取最新版本的 EMQX 安装包：
👉 EMQX 5.0 官方安装文档（Windows）
在页面中找到适用于 Windows 平台的版本，推荐下载emqx-5.0.26-windows-amd64.zip（64 位系统适用）。该版本基于 Erlang OTP 24 构建，支持主流 Windows 系统。
⚠️ 注意：请确保选择与操作系统架构匹配的版本（如 x64 / amd64），避免因架构不兼容导致启动失败。
1.2 安装步骤：解压到指定目录
下载完成后，将压缩包解压至一个路径不含中文、空格或特殊字符的目录下。例如：
D:\emqx✅ 推荐路径示例：
C:\emqxD:\emqxE:\emqx
❌ 避免使用以下路径：
D:\我的EMQX\emqx-5.0.26C:\Program Files\EMQXD:\emqx v5.0.26
📌 原因说明：EMQX 底层依赖 Erlang 虚拟机（Erlang/OTP），其 Windows 版本对非 ASCII 字符路径存在严重兼容性问题，容易引发
beam.smp.dll加载失败等错误。
解压后目录结构如下：
emqx/ ├── bin/ │ ├── emqx.bat │ ├── emqx.cmd │ └── ... ├── conf/ │ ├── emqx.conf │ └── ... ├── data/ ├── lib/ └── logs/1.3 打开终端窗口
进入解压后的bin目录（如D:\emqx\bin），按住键盘上的Shift 键，同时右键点击空白区域，选择「在此处打开终端窗口」。
✅ 此操作可快速打开命令行工具，无需手动切换路径。
1.4 启动服务
在终端中输入以下命令启动 EMQX 服务：
.\emqx start❗常见报错及解决方案
报错信息：
Unable to load emulator DLL (D:\emqx-5.0.26-windows-amd64\erts-12.3.2.11\bin\beam.smp.dll) 此时不应有 SET。 D:\emqx-5.0.26-windows-amd64\bin>@if ===/ SET data_dir=" D:\emqx-5.0.26-windows-amd64\bin>常见原因分析与解决方法：
1. 安装路径包含中文或特殊字符（最常见）
- 现象：路径中出现中文、空格、括号、斜杠等非英文字符。
- 影响：Erlang VM 在解析路径时会出错，无法正确加载
beam.smp.dll。 - 解决方式：
- 将整个 EMQX 文件夹移动到纯英文路径，如
D:\emqx。 - 重新进入
D:\emqx\bin目录，再次执行.\emqx start。
- 将整个 EMQX 文件夹移动到纯英文路径，如
✅ 检查建议：使用
dir命令查看当前路径是否含有非法字符。
2. 缺少 Visual C++ Redistributable 运行时
- 原因：
beam.smp.dll是由 Microsoft Visual C++ 编译生成的动态链接库，需要运行时支持。 - 症状：即使路径正确，仍提示 DLL 加载失败。
- 解决方案：
- 下载并安装Microsoft Visual C++ Redistributable for Visual Studio 2015–2022 (x64)。
- 官方下载地址：
🔗 https://aka.ms/vs/17/release/vc_redist.x64.exe - 同时建议也安装 x86 版本（若不确定系统环境）：
🔗 https://aka.ms/vs/17/release/vc_redist.x86.exe
💡 提示：安装完成后必须重启计算机，否则更改可能不会生效。
3. Windows Server 2022 兼容性问题（特定场景）
- 当前系统版本为
10.0.20348，即Windows Server 2022。 - 已知问题：某些更新补丁版本下的 Windows Server 2022 存在与 Erlang OTP 24（
erts-12.3.2.11）之间的兼容性缺陷，导致 DLL 加载异常。 - 解决方案：
- 升级至EMQX 5.8.x 及以上版本（如 5.8.1、5.9.0），这些版本已升级至 Erlang OTP 25，修复了大量 Windows 平台兼容性问题。
- 或者保持当前版本，但确保系统已安装所有最新的累积更新（通过 Windows Update 完成）。
✅ 实际验证结果：用户在安装Visual C++ Redistributable 2015–2022 x64后，问题成功解决，服务正常启动。
1.5 启动成功确认
当看到如下输出时，表示服务已成功启动：
Starting EMQX... EMQX started successfully.✅ 可通过以下命令检查状态：
.\emqx status✅ 查看日志文件定位潜在问题：
logs/emqx.log二、访问 MQTT 服务器管理后台
2.1 访问 Web 管理界面
在浏览器中输入以下地址：
http://localhost:18083/🔧 若你在远程服务器部署，需替换
localhost为实际公网或局域网 IP 地址，例如：
http://192.168.1.100:18083/🛡️ 注意：首次访问前，请确保防火墙允许端口
18083和1883的入站连接。
2.2 登录默认账号
| 项目 | 默认值 |
|---|---|
| 用户名 | admin |
| 密码 | public |
点击「登录」按钮即可进入管理控制台。
⚠️ 首次登录会强制要求修改密码，以提升安全性。
2.3 修改初始密码
登录后弹出提示框，要求设置新密码：
- 输入当前密码
public； - 填写新密码（建议至少 8 位，包含大小写字母、数字和符号）；
- 点击「确认」完成修改。
✅ 成功后将跳转至主界面，显示服务器状态、连接客户端数、主题统计等信息。
2.4 初始功能概览
登录成功后，你可以在管理界面看到以下核心功能模块：
| 功能模块 | 说明 |
|---|---|
| Dashboard | 实时监控：在线客户端数、消息吞吐量、系统资源占用等 |
| Clients | 查看当前连接的 MQTT 客户端列表，支持断开连接 |
| Topics | 查看订阅的主题，支持发布测试消息 |
| Rules Engine | 配置规则引擎，实现数据转发、存储、告警等功能 |
| Plugins | 管理插件，如数据库集成、HTTP 回调等 |
| Configuration | 修改配置文件（如监听端口、认证方式、安全策略等） |
2.5 常见问题排查（补充）
| 问题 | 解决方案 |
|---|---|
无法访问http://localhost:18083 | 检查 EMQX 是否正在运行；确认端口未被占用；关闭防火墙临时测试 |
| 登录失败 | 检查用户名密码是否正确；确认是否已修改过密码；查看日志logs/emqx.log |
| 无法连接客户端 | 检查客户端是否配置正确的 broker 地址和端口（默认tcp://localhost:1883） |
日志报错Failed to bind listener | 端口被占用，使用 `netstat -ano |
2.6 示例：使用 MQTT.fx 测试连接
你可以下载并安装 MQTT.fx 工具进行客户端测试：
- 打开软件，新建连接；
- 设置：
- Broker:
tcp://localhost:1883 - Client ID:
test_client_01 - Username: （可选）
- Password: （可选）
- Broker:
- 点击「Connect」，成功后可在「Subscriptions」中订阅主题，如
test/topic； - 在「Publish」中发送消息，观察是否能被接收。
✅ 成功收到消息即表示 EMQX 服务运行正常，具备基本的 MQTT 消息收发能力。
三、MQTT客户端
3.1、MQTTX 下载
MQTTX 下载
https://mqttx.app/zh/downloads
https://gitcode.com/gh_mirrors/mq/MQTTX?utm_source=highlight_word_gitcode&word=mqttx&isLogin=1&from_link=0c99abd4fe7a05c226a7a10d80e6dc7c
3.2、 双击文件安装
MQTTX-Setup-1.11.0-x64.exe
安装步骤直接下一步到完成
3.3、设置中文
将MQTT5.0客户端工具的语言设置为“简体中文”，步骤下图所示。
3.4、建立mqtt连接 、添加主题
总结
| 步骤 | 关键点 |
|---|---|
| 1. 下载 | 选择windows-amd64版本 |
| 2. 解压 | 路径必须为纯英文、无空格、无中文 |
| 3. 安装运行时 | 必须安装 VC++ Redistributable 2015–2022 x64 |
| 4. 启动服务 | 使用.\emqx start |
| 5. 登录后台 | admin/public→ 修改密码 |
| 6. 测试通信 | 使用 MQTT 客户端工具验证连接与消息传递 |
✅ 完成以上步骤后，你的 EMQX MQTT 服务器已成功部署并可投入使用，可用于物联网设备接入、实时数据推送、远程控制等典型场景。
📌 建议后续根据业务需求配置 TLS 加密、JWT 认证、集群部署等高级功能，进一步提升系统安全性与可靠性。
