客户端接入示例

RunMQTT 使用标准 MQTT 协议，按应用语言选择客户端库即可，不需要专用 SDK。下面三个简短示例使用同一个测试主题，均通过 TLS 连接，使用 MQTT 3.1.1、QoS 1，并关闭保留消息。

准备凭证和接收端

先完成快速入门。保持终端 A 对 demo/hello 的订阅运行，收到 SUBACK 后再留出五秒，然后运行示例。发布设备需要 demo/hello 的发布权限，接收端需要该主题的订阅权限；每个连接使用不同的 Client ID。

在运行示例的终端设置以下变量，值从 RunMQTT 设备详情复制。MQTT_HOST 只填 TLS 主机名，不包含 mqtts:// 和 :8883。执行 read 后粘贴密码并回车，输入不会显示。配置命令适用于 Bash 或 Zsh。

export MQTT_HOST='<broker>.tls-broker.runmqtt.com'
export MQTT_USERNAME='<broker-id>/<device-name>'
read -r -s MQTT_PASSWORD
export MQTT_PASSWORD

不要将凭证加入版本控制。各示例使用运行环境的可信 CA 证书，并保持主机名校验开启；请确保运行环境的证书信任库已更新。

JavaScript / Node.js

使用 Node.js 22 或更新版本。在空目录执行 npm init -y 和 npm install mqtt@5，保存以下代码为 publish.mjs，然后在已配置环境变量的终端运行 node publish.mjs：

import mqtt from "mqtt";
import { randomUUID } from "node:crypto";

const { MQTT_HOST, MQTT_USERNAME, MQTT_PASSWORD } = process.env;
if (!MQTT_HOST || !MQTT_USERNAME || !MQTT_PASSWORD) {
  throw new Error("Set MQTT_HOST, MQTT_USERNAME and MQTT_PASSWORD");
}
const deadline = setTimeout(() => process.exit(1), 20000);
let client;
try {
  client = await mqtt.connectAsync(`mqtts://${MQTT_HOST}:8883`, {
    username: MQTT_USERNAME,
    password: MQTT_PASSWORD,
    clientId: `js-${randomUUID().slice(0, 12)}`,
    protocolVersion: 4,
    keepalive: 60,
    connectTimeout: 10000,
    reconnectPeriod: 0,
  });
  await client.publishAsync("demo/hello", '{"language":"javascript"}', {
    qos: 1,
    retain: false,
  });
} finally {
  if (client) await client.endAsync(true);
  clearTimeout(deadline);
}

Python

使用 Python 3.9 或更新版本。执行 python3 -m venv .venv 创建虚拟环境，通过 source .venv/bin/activate 激活，再执行 python -m pip install 'paho-mqtt>=2,<3'。保存为 publish.py，运行 python publish.py：

import os
import ssl
import uuid
from paho.mqtt import publish

publish.single(
    "demo/hello",
    payload='{"language":"python"}', qos=1, retain=False,
    hostname=os.environ["MQTT_HOST"], port=8883,
    client_id="py-" + uuid.uuid4().hex[:12], keepalive=60,
    auth={"username": os.environ["MQTT_USERNAME"],
          "password": os.environ["MQTT_PASSWORD"]},
    tls=ssl.create_default_context(),
)

这个辅助函数适合首次发布验证。需要长期订阅、回调和重连管理时，使用 Paho 的 Client API。

Java

在已有 Java Maven 项目的 pom.xml 中，将以下依赖加入 dependencies：

<dependency>
  <groupId>org.eclipse.paho</groupId>
  <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
  <version>1.2.5</version>
</dependency>

将以下类保存为 src/main/java/RunMqttExample.java。执行 mvn compile 构建，在 IDE 的运行配置中设置前面的三个环境变量，再运行 main 方法。Paho Java 用 ssl:// 表示 TLS 连接，对应 MQTT.js 的 mqtts://。

import java.nio.charset.StandardCharsets;
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;

public class RunMqttExample {
    public static void main(String[] args) throws Exception {
        MqttConnectOptions options = new MqttConnectOptions();
        options.setUserName(System.getenv("MQTT_USERNAME"));
        options.setPassword(System.getenv("MQTT_PASSWORD").toCharArray());
        options.setMqttVersion(MqttConnectOptions.MQTT_VERSION_3_1_1);
        options.setConnectionTimeout(10);
        options.setKeepAliveInterval(60);
        options.setHttpsHostnameVerificationEnabled(true);
        MqttClient client = new MqttClient(
            "ssl://" + System.getenv("MQTT_HOST") + ":8883",
            MqttClient.generateClientId(), new MemoryPersistence());
        client.setTimeToWait(10000);
        try {
            client.connect(options);
            client.publish("demo/hello",
                "{\"language\":\"java\"}".getBytes(StandardCharsets.UTF_8),
                1, false);
        } finally {
            try {
                if (client.isConnected()) client.disconnectForcibly(1000, 1000);
            } finally {
                client.close();
            }
        }
    }
}

确认接收并接入业务

快速入门中的订阅端应收到 demo/hello，内容分别为 {"language":"javascript"}、{"language":"python"} 或 {"language":"java"}。检查接收端，不要只看发布进程是否成功退出；发布确认不代表应用已经收到或处理消息。30 秒内没有收到时，停止测试并按故障排查处理。结束后执行 unset MQTT_PASSWORD。

这些示例用于首次连接验证，不是长期运行的消费者。接入应用时补上订阅确认检查、有上限的重试、正常退出和业务去重。具体参见设备策略、会话与消息投递和共享订阅。

浏览器应用必须使用 RunMQTT 显示的完整 WSS 地址，例如 wss://<broker>.tls-broker.runmqtt.com/mqtt。Node.js 环境变量和 Java/Python 代码不能直接用于浏览器；不要将共用设备凭证打包进公开 JavaScript。

使用编程助手快速接入

把项目语言、框架、需要发布和订阅的主题，以及本页文档交给 Codex、Claude Code、OpenCode 等编程助手。真实密码放在本地环境或密钥管理服务中，提示词只使用占位信息。可以按项目情况调整下面这段请求：

请验证当前项目的 MQTT 连接及消息收发。
TCP（非加密）：<从 RunMQTT 复制 TCP 地址>
TLS（加密）：<从 RunMQTT 复制 TLS 地址>
MQTT 用户名：<设备用户名>
Client ID：<设备 Client ID>
密码：从本地环境变量 MQTT_PASSWORD 读取，未配置时提示我配置。
Topic 权限：<填写模板中的 Topic 过滤器和发布/订阅权限>
根据以上权限选择具体主题，测试消息是否实际收到。
说明使用的连接方式和测试结果；缺少权限或配置时给出提示。

使用 Go、C#、C/C++ 等其他语言时，也可以让助手按相同的连接和权限要求选择维护中的客户端库。检查生成的改动并通过消息接收验证后，再接入业务流量。SDK 文档：MQTT.js、Paho Python、Paho Java。