企业官网建设流程全解析

• 开发工具
• 物联网
• 后端

MQTTX CLI 是开源项目 MQTTX 提供的命令行版 MQTT 5.0 客户端工具（仓库路径 cli/），它让开发者在没有图形界面的环境（服务器、CI、容器、AI Agent）中也能快速完成 MQTT Broker 的连接调试、消息收发、性能压测与场景化数据模拟。读完本文，你将掌握mqttx的完整安装方式、conn/pub/sub三个核心命令的全部参数、基于bench的压测方法论，以及用simulate和自定义脚本模拟真实物联网数据流量的实战方案。

MQTTX CLI 是什么

MQTTX CLI 是一款开源的 MQTT 5.0 命令行客户端工具，被称为“命令行上的 MQTTX”。它面向无需图形化界面的场景，帮助开发者更快地开发和调试 MQTT 服务与应用。MQTT（Message Queuing Telemetry Transport，消息队列遥测传输）是一种基于发布/订阅范式的轻量级消息协议，专为受限设备和低带宽、高延迟或不可靠的网络设计，由 IBM 发布。

与桌面版不同，CLI 以单条命令完成连接、发布、订阅、压测和模拟等操作，且支持 MQTT 3.1、3.1.1 与 5.0 三种协议版本。从 命令注册入口 可以看到，mqttx基于 Node.js 与 MQTT.js 构建，整个命令体系通过 commander 注册，顶层提供check、init、conn、pub、sub、bench、simulate、ls等子命令。

安装 MQTTX CLI

安装前请注意区分当前系统环境的 CPU 架构。

macOS

下载二进制文件并快速安装最新的 MQTTX CLI 稳定版：

• Intel Chip

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-macos-x64 sudo install ./mqttx-cli-macos-x64 /usr/local/bin/mqttx

• Apple Silicon

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-macos-arm64 sudo install ./mqttx-cli-macos-arm64 /usr/local/bin/mqttx

• Homebrew

brew install emqx/mqttx/mqttx-cli

Linux

• x86-64

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-linux-x64 sudo install ./mqttx-cli-linux-x64 /usr/local/bin/mqttx

• ARM64

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-linux-arm64 sudo install ./mqttx-cli-linux-arm64 /usr/local/bin/mqttx

Windows

Windows 用户请到 MQTTX 的发布页面内，找到对应系统架构的exe包，手动下载后使用。

NPM

npm install mqttx-cli -g

Docker

docker pull emqx/mqttx-cli docker run -it --rm emqx/mqttx-cli

说明：Docker 方式不会在宿主机创建mqttx命令，且容器内解析的 broker 主机名时，localhost指的是容器自身。如需以 Docker 方式调用，请参考仓库根目录的 INSTALL.md 中关于镜像标签选择与mqttx --version/mqttx --help验证步骤的说明。

其它平台

从 MQTTX 的发布页面内下载对应的二进制文件。从源码看，package.json 中 pkg 打包目标覆盖了linux-x64、linux-arm64、macos-x64、macos-arm64、win-x64、win-arm64以及 alpine 变体，构建产物统一输出到release目录。

AI Agent 支持

MQTTX CLI 除了面向人类开发者，也面向 AI Agent：

安装或更新 MQTTX CLI

INSTALL.md 提供了面向 Agent 的安装与更新步骤，包括环境检测、安装渠道选择和版本验证。可以将下面的提示词交给 Agent：

读取 https://raw.githubusercontent.com/emqx/MQTTX/main/INSTALL.md，按照其中的步骤为当前环境安装或更新 MQTTX CLI，并验证命令路径和版本。

该文档建议 Agent 先通过uname -s/uname -m（macOS/Linux）或 PowerShell 的架构检测命令（Windows）检查环境，再选择 npm、Homebrew、独立二进制或 Docker 渠道，并在安装后运行mqttx --version、mqttx pub --help、mqttx sub --help验证命令路径与版本。

使用 MQTTX CLI skill

仓库提供了 mqttx-cli skill，帮助 Agent 使用 MQTTX CLI 完成连接检查、消息收发、MQTT 5 功能验证、TLS/认证、编解码、压测、数据模拟和故障排查。通过 Skills CLI 安装：

npx skills add emqx/MQTTX --skill mqttx-cli

从本地源码安装时，在仓库根目录运行npx skills add . --skill mqttx-cli。也可以将整个 skills/mqttx-cli 目录（包括references）复制到 Agent 支持的技能目录，或让 Agent 直接读取其中的SKILL.md。

安装后，可以这样描述任务：

使用 mqttx-cli skill，验证本地 127.0.0.1:1883 broker 的消息收发。使用 mqttx-test/ 下的唯一 topic，在 15 秒内结束检查，并报告结果。

快速使用

安装完成后，可在终端直接运行mqttx命令。

Connect

mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public'

Subscribe

mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883

Publish

# Publish a single message mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI' # Publish multiple messages (multiline) mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -s -M

从 pub 的实现 可以看到，-s -M（stdin + multiline）组合会通过管道把标准输入的每一行当作一条独立消息依次发布；若直接使用-m指定消息体，则在连接成功后立即发布单条消息，其中 WebSocket（ws/wss）且 QoS 为 0 的场景会延迟 2 秒关闭连接，以确保消息完成发送。

Benchmark

# Connect Benchmark mqttx bench conn -c 5000 # Subscribe Benchmark mqttx bench sub -c 5000 -t bench/%i # Publish Benchmark mqttx bench pub -c 5000 -t bench/%i

Simulate

# Specify a local scenario and start the simulation mqttx simulate -sc tesla -c 10 # Specify a scenario file and start the simulation mqttx simulate -f <scenario file path> -c 10 # List the built-in scenarios mqttx ls -sc

全局参数

mqttx --help

从源码看，除了上表所列命令外，还注册了init（初始化配置文件，见 init.ts）与ls（列出内置场景，见 ls.ts）两个命令；check命令仅检查更新，并不执行安装。

连接命令conn

mqttx conn --help

从 conn.ts 的源码可以看出，conn命令在连接成功后保持在线，并监听connect/error/reconnect/close/disconnect五个事件；当重连次数超过--maximum-reconnect-times时客户端会主动断开并提示reconnectTimesLimit。连接参数最终经 parse.ts 中的parseConnectOptions组装成 MQTT.js 的IClientOptions：TLS 的key/cert/ca通过fs.readFileSync读取为 Buffer，--insecure对应rejectUnauthorized = false，遗嘱消息及其 MQTT 5 属性（延迟间隔、内容类型、响应主题、关联数据、用户属性）也会在此统一装配。

订阅命令sub

mqttx sub --help

在 sub.ts 的实现中，-t支持一次订阅多个主题（<TOPIC...>），每个主题会通过parseSubscribeOptions生成独立的订阅选项（QoS、nl、rap、rh、订阅标识符等）。接收消息时会输出received_at、topic、qos、size、payload等字段，若开启-v还会打印原始 MQTT 数据包。--output-mode clean模式下，每条消息以独立 JSON 对象（含topic、payload、packet）连续输出，方便配合jq等流式解析工具做二次处理。

发布命令pub

mqttx pub --help

除上表参数外，从 pub 命令定义 中还可以看到--file-read <PATH>（从文件读取消息体）、-S, --payload-size <SIZE>（生成指定大小随机 Payload，如 1KB、512B、2MB，仅在未指定-m/-s/-M/--file-read时生效）、-Ap, --avsc-path <PATH>（AVRO Schema 编码）与-am, --authentication-method（MQTT 5 增强认证，支持 SCRAM-SHA-1/256/512）等扩展能力；发布时也不允许向含+、#通配符的主题发送消息（见 parse.ts 中的parsePubTopic）。

性能测试bench

性能测试命令与普通命令参数基本相同，以下仅列出新增或有变化的参数。

连接性能测试

mqttx bench conn --help

订阅性能测试

mqttx bench sub --help

发布性能测试

mqttx bench pub --help

从 bench 实现 与 multiPub 可以看出，bench系列命令会按-c的数量逐个创建客户端（每个客户端 ID 通过getBenchClientId使用%i占位符生成唯一值），每隔-i毫秒创建下一个连接；全部连接建立后，发布端按-im间隔循环发送消息并实时统计Published total与message rate。结合 pub.ts 定义 可知，发布端还额外支持-L, --limit <NUMBER>（最大发送消息数，0 表示不限）、--file-read（从文件循环读取消息体）与--split [CHARACTER]（按指定字符切分文件内容逐条发送）等参数。bench pub与bench sub的-t主题均支持%u（用户名）、%c（客户端 ID）、%i（索引）三种占位符替换。

模拟器simulate

simulate用于模拟特定场景下 MQTT 发布消息操作。模拟器命令与发布性能测试参数基本相同，以下仅列出新增或有变化的参数。

mqttx simulate --help

--scenario与--file参数必须指定一个，如果同时指定，优先使用--file参数。从 checkScenarioExists 的校验逻辑看，指定场景名时会在本地内置场景列表中查找，指定文件时则要求文件存在且以.js结尾。

自定义物联网数据模拟脚本示例

以下脚本生成随机的温度和湿度数据：

/** * MQTTX 场景文件示例 * * 此脚本生成随机的温度和湿度数据。 */ function generator (faker, options) { return { // 如果没有返回主题，则使用命令行参数中的主题。 // 主题格式：'mqttx/simulate/myScenario/' + clientId, message: JSON.stringify({ temp: faker.number.int({ min: 20, max: 80 }), // 在 20 到 80 之间生成随机温度。 hum: faker.number.int({ min: 40, max: 90 }), // 在 40 到 90 之间生成随机湿度。 }) } } // 导出场景模块 module.exports = { name: 'myScenario', // 场景名称 generator, // 生成器函数 }

场景文件是一个 CommonJS 模块，导出name（场景名称）和generator（生成器函数）。generator接收faker（来自 @faker-js/faker 的实例，用于生成各种随机数据）与options（当前连接参数，如clientId），返回一个包含message（可选的topic）的对象；若返回对象中不带topic，则使用命令行-t指定的主题。

仓库内置了多个真实场景可供参考，例如 tesla.ts 模拟 Tesla 车辆遥测数据，IEM.ts、smart_home.ts、weather.ts 分别对应智能电表、智能家居与气象数据；scripts-example/IoT-data-scenarios/ 目录还提供了配套的 JavaScript 版本示例（如 IEM.js、smart_home.js）。从 multiPub 的实现看，模拟运行时每个连接会独立调用simulator.generator(options)生成消息，并按-im间隔持续发布，模拟器场景名会替换主题中的%sc占位符。

列表命令ls

list命令提供了可用资源的概览。目前，该命令仅支持列出内置的场景。

mqttx list --help

内置场景

可以使用--scenarios选项来显示内置场景的列表：

mqttx list --scenarios

这个命令会输出一个表格，显示每个内置场景的名称和描述（见 ls.ts 的实现，它动态读取cli/src/scenarios目录下的.js场景模块并组装成表格）。如果想在模拟命令中使用其中一个，只需在--scenario选项中指定场景名称：

mqttx simulate --scenario <SCENARIO>

未来，list命令将添加更多选项和功能。

配置文件的保存与加载

在conn、pub、sub、bench、simulate等命令中都支持--save [PATH]与--config [PATH]（源码中对应的选项名为--save-options/--load-options，默认路径为当前目录下的mqttx-cli-options.json），文件支持 JSON 和 YAML 两种格式。其底层实现位于 options.ts：

• 保存：handleSaveOptions会按命令类型（如conn、pub）把当前命令的参数写入配置文件，若文件已存在则与旧配置合并（mergeOptions）；
• 加载：handleLoadOptions从配置文件中读取对应命令类型的参数，并用当前命令行显式传入的参数覆盖（filterOptions('cli', opts)），即“命令行参数优先”。

此外，mqttx init（见 init.ts）可以在用户主目录下交互式生成~/.mqttx-cli配置（INI 格式），其中包含默认的输出模式、协议、Host、端口、最大重连次数以及用户名/密码，作为各命令默认值来源。

与 EMQX 更好的合作

MQTTX 为连接测试 EMQX 等 MQTT 消息服务器而生，一键式的连接方式和简洁的命令行可以帮助您快速连接到 EMQX 或 EMQX Cloud 调试并探索其功能特性。

开发

Node 环境的推荐版本：

• v18..

# 克隆项目 git clone git@github.com:emqx/MQTTX.git # 安装依赖 cd MQTTX/cli yarn install # 编译和热重载以进行开发 yarn run dev # 编译和压缩以构建生产版本 yarn run build

构建成功后，会在dist目录里出现构建成功的相应的文件，需要在 Node.js 环境中使用。如果需要打包一个二进制可执行文件，请参考以下命令：

# 全局安装 pkg npm install pkg -g # 构建二进制可执行文件 pkg package.json

构建成功后，在release目录里可以看到对应各系统的二进制可执行文件了。从 package.json 可以看到，打包目标覆盖 Linux/macOS/Windows 的 x64 与 arm64 架构（含 Alpine 变体），运行环境要求 Node 18。

技术栈与测试

MQTTX CLI 的核心技术栈包括：

• TypeScript
• Node.js
• pkg（二进制打包）
• MQTT.js（MQTT 客户端库）

仓库在 cli/src/tests/ 中提供了完善的测试覆盖，包括连接/发布/订阅命令的集成测试（conn.test.ts、pub.test.ts、sub.test.ts），以及参数解析、Protobuf/Avro 编解码、SCRAM 认证、Payload 生成等工具函数的单元测试，可通过yarn test（Jest）运行。

社区与 License

• 访问 EMQ 问答社区以获取帮助，也可以分享您的想法或项目。
• 添加小助手微信号emqmkt，加入 EMQ 微信技术交流群。
• 加入 MQTTX 的 Discord，参与实时讨论。
• 关注 EMQ 的 bilibili，获取最新物联网技术分享。

MQTTX CLI 使用 Apache License 2.0 开源协议，详见仓库根目录的 LICENSE。

• 开发工具
• 物联网
• 后端