消息队列 MQTT 版使用 curl 进行 MQTT 通信

﻿curl 从 7.70.0 版本起原生支持 MQTT 协议，而自 curl 8.19.0版本起，开发者已经可以在终端中通过 MQTTS（基于 TLS 的 MQTT）进行加密通信。这意味着在大多数 Linux / macOS 系统上，无需安装任何额外的 MQTT 客户端工具，一条命令即可完成 MQTT 消息的发布与订阅，推荐使用于连通性测试与验证和快速、临时消息传递场景中。
前提条件
curl 版本要求：
基础 MQTT 通信（mqtt://）：curl ≥ 7.70.0
TLS 加密通信（mqtts://）：curl ≥ 8.19.0
MQTT 服务：消息队列 MQTT 版的集群接入点地址获取方式如下：
登录 MQTT 控制台。
在左侧导航栏选择资源管理 > 集群管理，选择好地域后，单击目标集群的“ID”，进入基本信息页面。
在接入信息模块，可以获取 MQTT 接入点信息。
﻿
运行以下命令确认 curl 版本及协议支持情况，在输出的 Protocols 一行中，确认包含 mqtt（如需 TLS 加密，还应包含 mqtts）：
curl --version
URL 格式说明
curl 使用 URL 来指定 MQTT 连接参数，格式如下：
mqtt[s]://[username:password@]host[:port]/topic
组件
说明
示例
mqtt://
非加密连接，默认端口 1883
mqtt://mqtt-xxx-public.mqtt.tencenttdmq.com
mqtts://
TLS 加密连接，默认端口 8883
mqtts://mqtt-xxx-public.mqtt.tencenttdmq.com
username:password
认证凭据（可选）
admin:public@mqtt-xxx-public.mqtt.tencenttdmq.com
/topic
MQTT 主题
/test
port
端口号（可选），不填写时 curl 将自动使用标准默认端口（1883 用于 mqtt://，8883 用于 mqtts://）
1883
订阅消息
打开一个终端窗口，运行以下命令订阅主题 curl/test：
curl -sN \\
  -u "your-username:your-password" \\
  mqtt://mqtt-xxx-public.mqtt.tencenttdmq.com:1883/curl/test
参数说明：
-s：静默模式，不显示进度条。
-N：禁用输出缓冲，确保收到消息后立即显示。
命令运行后，终端将保持连接并等待接收消息。
说明：
curl 订阅输出的原始数据为二进制格式（包含 2 字节主题长度前缀 + 主题 + 消息内容），终端中可能出现少量乱码字符属于正常现象。
可通过消息队列 MQTT 版的控制台 > 客户端管理 观察到新增客户端，点击详情即可查看相应的客户端订阅、客户端事件及客户端消息轨迹等内容。
﻿
发布消息
保持订阅终端不关闭，另外打开一个终端窗口，运行以下命令向 curl/test 主题发布一条消息：
curl \\
  -u "your-username:your-password" \\
  -d "Hello TDMQ from curl" \\
  mqtt://mqtt-xxx-public.mqtt.tencenttdmq.com:1883/curl/test
参数说明：
-d：指定要发布的消息内容。
发布成功后，切换到订阅终端，即可看到收到的消息。至此，您已完成了一次完整的 MQTT 发布/订阅通信。
同时，也可通过控制台上的消息查询查看此条消息从生产到消费的完整路径。
﻿
TLS 证书验证
单向认证（默认服务端证书）
单向认证（自定义服务端证书）
curl \\
  -u "your-username:your-password" \\
  -d "Hello TDMQ from curl" \\
  mqtts://mqtt-xxx-public.mqtt.tencenttdmq.com:8883/curl/test
curl \\
  --cacert /path/to/ca.crt \\
  -u "your-username:your-password" \\
  -d "Hello TDMQ from curl" \\
  mqtts://mqtt-xxx-public.mqtt.tencenttdmq.com:8883/curl/test
双向认证
# 支持多个客户端复用同一套客户端证书
curl \\
  --cacert /path/to/ca.crt \\
  --cert /path/to/client.crt \\
  --key /path/to/client.key \\
  -u "your-username:your-password" \\
  -d "Hello TDMQ from curl" \\
  mqtts://mqtt-xxx-public.mqtt.tencenttdmq.com:8883/curl/test
一机一证（BYOC）
curl \\
  --cacert /path/to/ca.crt \\
  --cert /path/to/client.crt \\
  --key /path/to/client.key \\
  -d "Hello TDMQ from curl" \\
  mqtts://mqtt-xxx-public.mqtt.tencenttdmq.com:8883/curl/test
常用参数速查
参数
说明
适用场景
-N
禁用输出缓冲，消息实时显示
订阅（必选）
-d “payload”
指定发布的消息内容
发布
-u username:password
用户名和密码认证
需认证的 Broker
-s
静默模式，不显示进度信息
订阅
-v
详细模式，显示连接握手过程
调试排查
--cacert
指定 CA 证书文件
TLS 连接
--cert
指定客户端证书
mTLS 认证
--key
指定客户端私钥
mTLS 认证
已知限制
使用 curl 进行 MQTT 通信时，请注意以下限制：
限制项
说明
QoS 等级
仅支持 QoS 0，不支持 QoS 1 和 QoS 2，如需消息可靠传输，请使用专业客户端 SDK。
通配符订阅
不支持 + 和 # 通配符
主题数量
每条命令仅支持操作一个主题
持久会话
不支持跨连接的持久会话
Retain 标志
发布消息时无法设置 retain 标志
原生 curl 工具仅适用于快速验证消息收发流程。如需更完整的 MQTT 特性支持，您可以通过消息队列 MQTT 版的数据面接口，通过 HTTP POST 发布 MQTT 消息来实现。
﻿

组件	说明	示例
`mqtt://`	非加密连接，默认端口 1883	`mqtt://mqtt-xxx-public.mqtt.tencenttdmq.com`
`mqtts://`	TLS 加密连接，默认端口 8883	`mqtts://mqtt-xxx-public.mqtt.tencenttdmq.com`
`username:password`	认证凭据（可选）	`admin:public@mqtt-xxx-public.mqtt.tencenttdmq.com`
`/topic`	MQTT 主题	`/test`
`port`	端口号（可选），不填写时 curl 将自动使用标准默认端口（1883 用于 mqtt://，8883 用于 mqtts://）	`1883`

参数	说明	适用场景
`-N`	禁用输出缓冲，消息实时显示	订阅（必选）
`-d` `“payload”`	指定发布的消息内容	发布
`-u` `username:password`	用户名和密码认证	需认证的 Broker
`-s`	静默模式，不显示进度信息	订阅
`-v`	详细模式，显示连接握手过程	调试排查
`--cacert`	指定 CA 证书文件	TLS 连接
`--cert`	指定客户端证书	mTLS 认证
`--key`	指定客户端私钥	mTLS 认证

限制项	说明
QoS 等级	仅支持 QoS 0，不支持 QoS 1 和 QoS 2，如需消息可靠传输，请使用专业客户端 SDK。
通配符订阅	不支持 `+` 和 `#` 通配符
主题数量	每条命令仅支持操作一个主题
持久会话	不支持跨连接的持久会话
Retain 标志	发布消息时无法设置 retain 标志

使用 curl 进行 MQTT 通信

本页目录：

前提条件

URL 格式说明

订阅消息

发布消息

TLS 证书验证

常用参数速查

已知限制