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

MQTTX CLI 是 MQTTX 项目提供的命令行 MQTT 客户端，覆盖conn、pub、sub以及bench、simulate等全部常用操作。本文以仓库内 MQTTX CLI 故障排查文档 为骨架，结合 CLI 源码 与配套参考文档，系统讲解配置加载、凭据安全、连接认证、TLS、订阅投递与输出解析等故障场景的定位方法。读完本文，你将掌握一套"基于观察证据、分层次隔离客户端 / 网络 / Broker 行为"的诊断流程，能独立排查从"命令找不到"到"订阅收不到消息"的常见问题。

上图展示了 MQTTX CLI 的典型使用形态：上方终端执行mqttx sub订阅并接收消息，下方终端执行mqttx pub发布消息。

排查前置条件：建立可复现的诊断环境

在动手排查之前，先确认三件事，否则后续所有判断都可能失真：

1. 确认命令与版本：执行mqttx --version确认 CLI 可用且版本符合预期；对每条要用的子命令执行mqttx <command> --help，以已安装版本的帮助输出为权威依据——发布渠道不同，子命令支持可能有差异。
2. 安装与路径：若mqttx缺失或版本异常，遵循仓库根目录的 INSTALL.md 重新安装，并在重装前检查 PATH 与安装目录的所有权归属。
3. 外部超时与进程管控：连接、订阅类任务必须设置有限观察期限，并持有所启动进程的句柄。GNU 环境下可用timeout --signal=INT --kill-after=2s 10s mqttx conn ...；注意timeout返回 124 表示的是包装层超时，而非 Broker 认证错误，需要结合捕获的诊断输出判断连接是否已在超时前成功。macOS（无 GNUtimeout）与 Windows 上应使用子进程 API 配合期限、终止升级与最终等待，不要以无界命令作为兜底。

仓库 CLI 命令注册入口 中可以看到，1.13.0 版本的 CLI 并未提供通用的--timeout、--max-messages、--json或--output jsonl这类全局旗标，--reconnect-period 0只是禁用自动重连而不是整体期限，conn成功后保持连接、sub会持续监听直到被停止——这些都是排查时必须牢记的边界。

配置与凭据：故障排查的第一现场

默认配置~/.mqttx-cli/config与mqttx init

CLI 会从~/.mqttx-cli/config读取默认值（host、port、protocol、username、password 等）。mqttx init是交互式命令，会写入或覆盖该文件——因此对于一次性自动化调用，通常不需要先执行init，直接显式传参即可。

在 1.13.0 中不存在init --yes之类的非交互旗标，无头（headless）任务绝不能停留在init的交互提示上。若需要非交互式配置，可参考 配置与工具命令 直接手写 INI 配置，并保留既有无关设置、保护凭据。一个最小示例：

[default] output = text [mqtt] host = 127.0.0.1 port = 1883 protocol = mqtt max_reconnect_times = 10

合法输出模式只有text（spinner 风格）与log（带时间戳日志），两者都不是 JSON 输出。从 配置加载实现 可以看到：output与protocol会做合法性校验（VALID_OUTPUT_MODES、VALID_PROTOCOLS），解析失败时打印错误并回退到默认配置；max_reconnect_times由于使用了||回退逻辑，在 INI 中写 0 会回退为默认值，需要"零重连"时请改用显式 CLI 重连控制（如--reconnect-period 0）。

命令级选项文件：--load-options与--save-options

--load-options接受一个按命令名作为顶层键组织的 JSON 或 YAML 文件。原文档给出的最小示例（订阅场景）如下：

{ "sub": { "hostname": "127.0.0.1", "port": 1883, "protocol": "mqtt", "mqttVersion": 5, "topic": ["mqttx-test/example"], "qos": [1], "reconnectPeriod": 0, "maximumReconnectTimes": 0 } }

在外部期限约束下运行，例如：

mqttx sub --load-options ./mqttx-options.json

使用时必须注意选项文件的三个关键语义，这些均可在 选项文件加载实现 中印证：

• 键名采用内部 camelCase，不是 CLI 的短横线旗标拼写。例如--mqtt-version对应文件里的数值mqttVersion，MQTT 5 在文件里写作5，而 CLI 旗标写作-V 5.0。parseMQTTVersion在 参数解析 中的映射为：3.1 → 3、3.1.1 → 4、5/5.0 → 5。
• 加载的选项会替换默认选项对象（而非增量修补），因此任务所需的连接与操作设置必须写全；随后显式 CLI 选项覆盖加载值——handleLoadOptions正是通过{ ...config[commandType], ...filterOptions('cli', opts) }实现"文件值打底、CLI 值覆盖"。
• 各命令的顶层键：conn、pub、sub用各自命令名；bench conn用benchConn，bench pub用benchPub，bench sub用benchSub，simulate用simulate。若文件中找不到对应命令的键，validateOptions会报错并以process.exit(1)退出。

常见键映射对照（详细清单见 配置与工具命令）：

还需要注意：

• 文件中的topic语义随命令不同：发布主题是字符串，订阅主题是数组（如上例"topic": ["mqttx-test/example"]）。
• JSON/YAML 值绕过 CLI 参数解析器，因此数字、布尔值、数组必须类型正确。
• 文件内的环境变量引用不会被展开——不要假设"password": "${PASS}"之类写法会生效。
• --save-options不是干运行：它会保存参数后继续执行连接/发布/订阅等网络操作，且可能把凭据写进文件。仅在"既要求保存又要求执行操作"时才使用它；否则应直接手工构造文件。

凭据安全与临时文件纪律

如果需要认证凭据，优先使用一个已存在的受保护文件，在对应命令条目中提供username与password字段。对于任务创建的临时凭据文件，必须：限制访问权限、不提交到版本库、任务结束后只删除自己创建的临时文件。不要把文件内容打印出来，也不要在最终报告中保存包含机密信息的命令行。-P/--password会把密码暴露在进程参数中，Shell 环境变量展开进-P依然会暴露最终参数，因此能走受保护选项文件时优先走文件。

从观察证据定位故障：诊断决策表

原文档给出了一张"观察 → 下一步检查"的决策表，这是整套排查方法的核心。下面逐行展开，并补充源码层面的验证依据：

这张表的要点在于：先记录观察到的客观事实，再决定下一步查什么，而不是根据"感觉"去改配置。尤其要区分四层证据——连接已建立、订阅被接受、发布在指定 QoS 下被确认、消息确实被匹配接收，这四者必须分开报告。

MQTT 版本与传输：兼容性故障排查

如果 Broker 只支持 MQTT 3.1.1：

• 使用-V 3.1.1，并省略所有 MQTT 5 专属选项（session expiry、user properties、topic alias、subscription identifier、no-local 等均属于 MQTT 5 特性，参见 连接与认证）。

如果使用 WebSocket 监听器：

• 核对-l ws/-l wss以及--path是否与 Broker 配置一致。注意--hostname是主机名/IP 而非完整 URL；-l只切换传输协议，不会自动更换端口默认值，必须显式指定端口。

从源码看，parseProtocol只接受mqtt、mqtts、ws、wss四种取值，parseMQTTVersion只接受3.1、3.1.1、5/5.0，非法值会立即报错退出——所以"版本/协议写错"通常会在命令行解析阶段就被拦截，而不是表现为连接失败。若连接报错早于Connected，优先怀疑 hostname、端口、网络与监听器，而不是 CLI 本身。

使用--debug深入诊断

--debug用于普通诊断手段不足时的最后一层排查：

• 它只在普通conn、pub、sub上启用 MQTT.js 调试（参见 CLI 命令注册入口 中这三个命令的--debug定义），不要把它传给bench/simulate子命令，除非已安装版本的帮助明确支持。
• 调试日志与报文输出可能包含敏感的连接或消息数据——提取相关细节、脱敏后再报告，不要把带凭据的原始输出原样贴出。
• 在没有把客户端、网络、Broker 三者行为分开取证的情况下，不要轻易把连接问题定性为 MQTTX 缺陷。

一套可复用的排查流程

综合上文，推荐按以下顺序收敛问题：

1. 环境层：确认mqttx存在且版本正确（INSTALL.md），查看对应子命令帮助，设置外部期限与进程句柄。
2. 配置层：检查~/.mqttx-cli/config是否注入了非预期默认值；若使用--load-options，核对顶层键名、camelCase 字段、类型与覆盖语义，凭据只走受保护文件。
3. 证据层：对照上面的诊断决策表，逐项记录"观察 → 下一步检查"，用默认输出模式做有界诊断（timeout包一层conn或sub），同时采集 stdout 与 stderr。
4. 判定层：区分"连接成功 / 订阅成功 / 发布确认 / 消息到达"四类证据分别报告；退出码 0 与空输出都不等于成功；必要时才用--debug并脱敏取证。

相关配套文档：完整命令工作流见 基础工作流，连接、TLS、SCRAM 认证细节见 连接与认证，配置与工具命令见 配置与工具命令，各子命令旗标可用性对照见 功能能力清单。

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