FAQ

什么是 MQTTX CLI？

MQTTX CLI（mqttx）是 EMQ 开源（Apache-2.0）的免费 MQTT 5.0 命令行客户端，支持 Windows、macOS 和 Linux。无需图形界面，即可在终端中连接 MQTT Broker、发布和订阅消息、进行性能测试以及模拟 IoT 数据。

如何安装 MQTTX CLI？

在 macOS 和 Linux 上运行：

curl -fsSL https://emqx.sh/mqttx | sh

在 Windows 上，于 PowerShell 中运行 irm https://emqx.sh/mqttx.ps1 | iex。Homebrew、NPM、Docker 等其他方式请参阅安装。

在中国大陆下载很慢怎么办？

设置 MQTTX_REGION=cn 即可从 EMQ 的中国大陆镜像下载。

curl -fsSL https://emqx.sh/mqttx | MQTTX_REGION=cn sh

$env:MQTTX_REGION = "cn"; irm https://emqx.sh/mqttx.ps1 | iex

如何在命令行中测试 MQTT Broker？

在一个终端中订阅，在另一个终端中发布：

mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI'

如果只需检查 Broker 能否连接，运行 mqttx conn -h 'broker.emqx.io' -p 1883。

如何通过 TLS 或 WebSocket 连接？

使用 -l, --protocol 选择 mqtt、mqtts、ws 或 wss。TLS 连接通过 --ca 指定 CA 证书，双向 TLS 还需要 --cert 和 --key。--insecure 会跳过服务器证书校验，仅建议在测试时使用。WebSocket 连接可通过 --path 设置路径（默认 /mqtt），通过 -wh 添加请求头。全部参数请参考开始使用。

MQTTX CLI 支持哪些 MQTT 版本？

支持 MQTT 5.0、3.1.1 和 3.1，默认使用 MQTT 5.0，可通过 -V, --mqtt-version 切换。MQTT 5.0 特性均以参数形式提供，例如用户属性（-up）、会话过期间隔（-se）以及订阅时的 Retain Handling（-rh）。

MQTTX CLI 能对 MQTT Broker 进行性能测试吗？

可以。mqttx bench conn、mqttx bench sub 和 mqttx bench pub 分别使用大量并发客户端测试连接、订阅和发布性能，例如 mqttx bench pub -c 5000 -t bench/%i。

MQTTX CLI 能生成模拟 IoT 数据吗？

可以。mqttx simulate 可以使用内置场景（通过 mqttx ls -sc 查看）或自定义 JavaScript 脚本发布数据，例如 mqttx simulate -sc tesla -c 10。

如何避免重复输入相同的参数？

使用 -so, --save-options 将参数保存为 JSON 或 YAML 文件，之后通过 -lo, --load-options 加载。运行 mqttx init 可以创建默认配置文件。

AI 编码 Agent 可以使用 MQTTX CLI 吗？

可以。mqttx-cli Agent Skill 可以让 Claude Code、Cursor 等 AI 编码 Agent 正确使用 MQTTX CLI 完成连接检查、发布订阅往返验证、性能测试和故障排查。安装命令为 npx skills add emqx/MQTTX --skill mqttx-cli。

如何检查更新？

运行 mqttx check 即可检查是否有新版本的 MQTTX CLI。从 v1.13.3 起，可运行 mqttx update 安装最新版本，详情请参阅更新。