5.7 云组态 MQTT 变量（# 前缀）

前面几节讲的都是「设备 publish 到服务器 Broker，服务器落库，云组态用项目变量读」。云组态还有另一条路：画面直接连 MQTT Broker，用 # 前缀的变量订阅/发布主题。

5.7.1 和项目变量的区别

	项目变量（无前缀）	MQTT 变量（# 前缀）
数据来源	服务器实时数据库的数据点	浏览器直连 Broker 订阅的主题
通道	WebSocket 推送 + HTTP 轮询兜底	浏览器里的 MQTT 客户端
是否落库	是	否，由画面自行接收并解析
能否做历史/事件触发	能	不能
能否连第三方 Broker	不能	能

选择原则：

• 数据本来就是通过 LP 云平台 Broker 上报的 → 用项目变量，同时具备历史和报警
• 数据在第三方 Broker 上，不方便搬到 LP 云平台服务器 → 用 MQTT 变量直接订阅
• 需要历史曲线、超限报警 → 必须走项目变量

5.7.2 变量写法

#主题名

例如 #sensor/temperature 表示订阅主题 sensor/temperature。

5.7.3 配置项（读 / 订阅）

在组态编辑器的变量选择器里切到「MQTT 变量」标签：

配置项	取值	说明
订阅 Topic	主题名	如 sensor/temperature
QoS 等级	0 / 1 / 2	默认 0
数据类型	数字（自动转换）	用 Number() 转，转不出来退回字符串
	字符串	原样当字符串用
	JSON 提取	按下面的 JSON 路径取字段
	原始数据	不做任何处理
JSON 路径	如 data.values[0].temp	仅「JSON 提取」时有效

JSON 路径支持数组下标，[0] 会被转成 .0 后逐层取值。例如 payload 为：

{"data":{"values":[{"temp":25.6}]}}

配置 JSON 路径 data.values[0].temp 就能取到 25.6。

5.7.4 配置项（写 / 发布）

控件的点击事件写 MQTT 变量时，配置项不同：

配置项	取值	说明
QoS 等级	0 / 1 / 2
消息格式	原始值	直接把值转成字符串发出
	JSON 模板	按模板拼 JSON
JSON 模板	如 {"value":}	模板里的 会被替换成实际值
retain	开 / 关	是否让 Broker 保留这条消息

用 JSON 模板时，发布前会先做一次 JSON 合法性校验，模板写错会在浏览器控制台给出告警。

5.7.5 回环抑制

画面自己 publish 出去的消息，如果又订阅了同一个主题，Broker 会把它回传回来。为了避免控件刚点下去就被自己发出的消息覆盖，发布后 1 秒内会忽略同主题的回传消息。

超过 1 秒的正常数据不受影响。

5.7.6 断线重连

浏览器里的 MQTT 客户端断线后会自动重连，重连成功后按各主题原来的 QoS 重新订阅，不需要手动处理。

5.7.7 注意事项

• 不填配置时的默认行为是 QoS0 + 原始数据，但完全没有配置对象时会走「智能默认」：能转成数字就转数字。为了行为可预期，建议每个 MQTT 变量都显式选好数据类型。
• 浏览器连接 MQTT 走的是 WebSocket，不是 1883 原生端口。连第三方 Broker 时对方必须开了 MQTT over WebSocket，否则浏览器连不上。
• MQTT 变量的数据只存在于当前打开的画面里，关掉页面就没有任何留存。

---