开始使用

准备 MQTT 服务器

公共的 MQTT 服务

如果您无需自行部署 MQTT 服务，您可以使用 EMQX 提供的在线公开版本进行快速测试：

Broker 地址: broker.emqx.io
Broker TCP 端口: 1883
Broker SSL 端口: 8883

全托管云原生 MQTT 消息服务

EMQX 提供全托管的云原生 MQTT 消息服务，能够通过可靠、实时的物联网数据传输、处理和集成，连接大量的物联网设备。您可以在几分钟内创建一个 MQTT 服务。

14 天免费试用

自行部署 MQTT 服务

如果您计划部署本地运行的 MQTT 服务，我们建议您下载并使用 EMQX。EMQX 是一款云原生分布式物联网 MQTT 消息服务器，能够高效可靠地连接大量物联网设备。

立即下载和安装 EMQX

以下是使用 Docker 快速安装 EMQX 的方式：

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

快速建立连接

准备好 Broker 后，点击左侧栏的 + 或新建连接，打开连接表单。

没有保存的连接时，欢迎页提供三个入口：

  • 新建连接：打开连接表单，也可以按 Cmd/Ctrl + N。
  • 连接公共 Broker：创建名为 broker.emqx.io 的连接，并立即连接到 broker.emqx.io:1883。
  • 导入数据：导入 JSON、YAML、CSV、XML 或 Excel 文件，成功后应用会重新加载。

MQTTX 空白连接页

mqttx-create

客户端连接信息

在连接表单中配置以下信息。

  1. Broker 信息
    Client ID、Host 和端口已有默认值，请按 Broker 的实际配置修改。
    • 名称：填写连接名称，例如 emqx_test。
    • Client ID：连接的唯一标识。点击输入框旁的刷新按钮可生成新的值。
    • Host：选择 mqtt:// 或 ws://；使用 TLS 时选择 mqtts:// 或 wss://。默认主机名为公共 Broker broker.emqx.io，可替换为自己的 Broker 主机名或 IP。
      • Path：使用 WebSocket 时填写服务端的端点路径，默认为 /mqtt。
    • 端口：填写所选协议的监听端口。下表为 EMQX 默认值；如果 Broker 修改过端口，请使用实际配置。
      协议EMQX 默认端口
      mqtt://1883
      mqtts://8883
      ws://8083
      wss://8084

    mqttx-brokerinfo
  2. 用户认证信息
    如果 Broker 开启了用户认证，请填写用户名和密码。
    mqttx-user
  3. SSL/TLS
    开启 SSL/TLS，可在 MQTTX 与 Broker 之间建立加密连接。
    • SSL/TLS：启用或禁用 TLS，默认关闭。
    • SSL Secure：校验服务端证书链和主机名，关闭后跳过这两项校验。开发环境或可信内网中测试未受信任的证书时可临时关闭；生产环境和外部连接应保持开启。
    • CA signed server certificate：使用受信任的 CA 校验服务端证书。
    • CA or Self-signed certificates：提供自定义证书。单向认证只需 CA File；双向认证还需 Client Certificate File 和 Client key file。点击各字段旁的文件夹图标选择文件。

    mqttx-certs
  4. 高级配置
    在高级区域设置连接超时、Keep Alive、Clean Session 或 Clean Start、自动重连和 MQTT 版本。
  5. MQTT 5.0
    MQTT 版本默认为 5.0，也可以选择 3.1 或 3.1.1。使用 MQTT 5.0 时，可配置会话过期间隔（Session Expiry Interval）、接收最大数量（Receive Maximum）和主题别名最大值（Topic Alias Maximum）等可选属性。
    mqttx-v5
  6. 遗嘱消息
    在遗嘱消息区域配置客户端意外断开时由 Broker 发布的消息。
    Last-Will-QoS 默认为 0，Last-Will-Retain 默认为 False。填写 Last-Will-Topic 和 Last-Will-Payload 即可完成配置。
    在 Last-Will-Payload 编辑器下方的格式选项中，可选择 Plaintext（默认）、JSON、Base64、Hex、CBOR 或 MsgPack。Base64 和 Hex 会忽略输入中的空白字符，发送解码后的字节；CBOR 和 MsgPack 将输入的 JSON 编码为二进制数据，Plaintext 和 JSON 则按原文发送。
    所选格式随连接保存；如果 Payload 不符合所选格式，会显示错误并阻止保存。切换格式会重新校验 Payload，但不会转换已有内容。

    注意： 发送二进制 Payload 时，请保持 有效载荷指示器 关闭；在 MQTT 5.0 中，开启该选项表示 Payload 是 UTF-8 文本。


    mqttx-willmessage

完成配置后，点击右上角的连接按钮，创建连接并连接到 Broker。

消息的发布与订阅

主界面

连接成功后，点击顶部连接名称旁的折叠按钮，可查看或修改基本配置。修改前先断开连接，再重新连接使其生效；每次连接成功后，面板会自动折叠。断开连接时，也可以通过右侧的配置按钮修改全部连接设置。

mqttx-main

添加订阅

点击左下角的 New Subscription，输入 Topic，并选择主题颜色，也可以使用随机颜色。订阅列表右上角的按钮可隐藏列表。

点击订阅可按主题筛选消息，再次点击可取消筛选，也可以直接切换到其他订阅。点击主题名称可复制主题，需要发布时可粘贴到发布区的主题输入框。

mqttx-topic

添加订阅时可以设置主题别名。订阅列表会显示别名，悬停时显示原始主题，便于区分较长的主题名称。

mqttx-topic-alias

在订阅弹窗中用逗号分隔多个 Topic，即可一次添加多个主题；主题别名也可以用逗号分隔。

mqttx-multi-topics

右键点击订阅可选择编辑、禁用或启用。禁用可临时停止接收该主题的消息，启用后即可恢复，无需重新输入主题。

mqttx-edit-topic

断开连接时，如果开启了 Clean Session（MQTT 3.x）或 Clean Start（MQTT 5.0），可以删除或禁用订阅。持久会话会阻止这些操作：MQTT 3.x 关闭 Clean Session，或 MQTT 5.0 关闭 Clean Start 且 Session Expiry Interval 大于 0 时，Broker 仍保留订阅。新增或编辑订阅仍需先连接。

消息发送与接收

在发布区输入已订阅的主题，选择 QoS 和 Retain，填写 Payload 后点击发送。右侧显示发送的消息，左侧显示接收的消息；向已订阅主题发布时，两侧都会出现对应消息。macOS 用户可按 Cmd + Enter 发送，其他系统使用 Ctrl + Enter。

mqttx-message

在发布区的 payload 选项中选择 Base64、Hex、JSON、Plaintext、CBOR 或 MsgPack。消息列表上方的格式选项用于解码接收的消息。

注意： CBOR 和 MsgPack 是高效的二进制格式，相比 JSON 可减小 Payload 体积；两者均使用 JSON 作为输入和输出。

如需使用 Protobuf 或 Avro 编解码，打开脚本 > 编解码。

使用发布区的箭头浏览之前发布过的 Payload。右键点击消息，可复制其 Payload 或主题。

每个连接单独保存发布区（Topic、QoS、Retain、Payload 和格式）及发布历史。尚未保存发布区时，会显示该连接最近发送的消息。升级时，旧版共享的发布历史会复制到每个连接。Topic 历史下拉列表中，每条记录的删除图标只删除该条记录。

至此，您就完成了一条 MQTT 消息的测试。