物联网通信基石：手把手在本地安装并运行Mosquitto MQTT代理

在物联网（IoT）和移动应用开发中，设备间的轻量级、异步通信至关重要。MQTT（消息队列遥测传输）协议正是为此而生，而 Mosquitto 则是 Eclipse 基金会旗下的一款开源、轻量级的 MQTT 消息代理（服务器），它实现了 MQTT 协议版本 5.0、3.1.1 和 3.1，是学习和开发 MQTT 应用的绝佳选择。

本文将带你从零开始，在本地计算机上安装并运行 Mosquitto 代理，并编写简单的客户端进行测试，为你构建物联网应用打下第一块基石。

一、 Mosquitto 安装指南

我们将分别介绍在 Windows、macOS 和 Linux 系统上的安装方法。

1. Windows 平台安装

对于 Windows 用户，最便捷的方式是使用预编译的二进制安装包。

访问下载页面：打开 Mosquitto 官方下载页面，找到 Windows 部分的安装包。通常推荐下载标有 “Windows Binary Installer” 的版本（如 mosquitto-2.0.18-install-windows-x64.exe）。
运行安装程序：下载完成后，以管理员身份运行安装程序。
遵循安装向导：
- 在 “Choose Components” 步骤，建议勾选所有组件，特别是 Install mosquitto broker as a system service（将代理安装为系统服务），这样 Mosquitto 可以随系统启动。
- 在 “Service Logon” 步骤，可以选择使用本地系统账户。
完成安装：安装完成后，Mosquitto 服务默认已启动。你可以通过 Win + R 打开运行窗口，输入 services.msc 并回车，在服务列表中找到 “Mosquitto Broker” 来查看和管理其状态。

验证安装：打开命令提示符（CMD）或 PowerShell，输入以下命令查看版本：

mosquitto --version

如果显示出版本信息（如 mosquitto version 2.0.18），则说明安装成功。

2. macOS 平台安装

macOS 用户推荐使用 Homebrew 包管理器进行安装，这是最简单高效的方法。

安装 Homebrew（如果尚未安装）：在终端（Terminal）中执行以下命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

使用 Homebrew 安装 Mosquitto：在终端中执行：
```
brew install mosquitto
```
启动 Mosquitto 服务：安装完成后，你可以使用 Homebrew 服务管理命令来启动 Mosquitto，并设置为开机自启：
```
brew services start mosquitto
```

验证安装：同样可以使用 mosquitto --version 命令验证。

3. Linux 平台安装（以 Ubuntu/Debian 为例）

大多数 Linux 发行版的官方仓库中都包含了 Mosquitto。

更新包列表：
```
sudo apt update
```
安装 Mosquitto 代理和客户端工具：
```
sudo apt install mosquitto mosquitto-clients
```
这个命令会同时安装代理服务器 (mosquitto) 和用于测试的客户端命令行工具 (mosquitto_sub, mosquitto_pub)。
管理服务： Mosquitto 通常会被安装为系统服务。你可以使用 systemctl 命令管理它：
- 启动服务：sudo systemctl start mosquitto
- 设置开机自启：sudo systemctl enable mosquitto
- 查看状态：sudo systemctl status mosquitto

验证安装：mosquitto --version 或 mosquitto_sub --help。

二、基础配置与运行测试

安装完成后，让我们先使用默认配置运行并测试 Mosquitto。

1. 使用命令行工具测试

Mosquitto 自带的客户端工具 mosquitto_sub（订阅者）和 mosquitto_pub（发布者）是快速测试代理是否工作的利器。

我们需要打开两个终端窗口。

终端 1：启动订阅者 订阅一个主题，例如 test/topic。
```
mosquitto_sub -h localhost -t "test/topic" -v
```
- -h localhost：指定连接的代理主机为本地。
- -t "test/topic"：指定要订阅的主题。
- -v：打印详细输出，包括主题名称。
运行后，这个终端会进入等待状态，监听 test/topic 主题上的消息。
终端 2：发布消息 向 test/topic 主题发布一条消息。
```
mosquitto_pub -h localhost -t "test/topic" -m "Hello, Mosquitto!"
```
- -m "Hello, Mosquitto!"：指定要发布的消息内容。

执行发布命令后，立即切换到终端 1，你应该能看到输出：

test/topic Hello, Mosquitto!

恭喜！这证明你的 Mosquitto 代理正在正常运行，并能正确处理 MQTT 的发布/订阅消息。

2. 理解默认配置

Mosquitto 的主配置文件通常位于：

Windows: C:\Program Files\mosquitto\mosquitto.conf
macOS (Homebrew): /opt/homebrew/etc/mosquitto/mosquitto.conf
Linux (Ubuntu): /etc/mosquitto/mosquitto.conf

默认配置已经足够用于本地基础测试。几个关键默认值：

listener 1883：在 1883 端口（MQTT 标准端口）上监听 TCP 连接。
允许匿名连接（无密码）：这在本地测试时很方便，但在生产环境是严重的安全风险。

三、使用 Python 客户端进行测试

除了命令行工具，我们更常用编程语言客户端来与 MQTT 代理交互。这里以 Python 为例，使用流行的 paho-mqtt 库。

安装 Paho-MQTT 客户端库：
```
pip install paho-mqtt
```

编写订阅者脚本 subscriber.py：

import paho.mqtt.client as mqtt
import time

# 定义回调函数，当接收到 CONNACK 响应（连接成功）时调用
def on_connect(client, userdata, flags, reason_code, properties):
    print(f"Connected with result code {reason_code}")
    # 订阅同一个主题
    client.subscribe("python/test")

# 定义回调函数，当收到来自服务器的消息时调用
def on_message(client, userdata, msg):
    print(f"{msg.topic} {msg.payload.decode()}")

# 创建 MQTT 客户端实例，使用 MQTT v5
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.on_connect = on_connect
client.on_message = on_message

# 连接到本地代理
client.connect("localhost", 1883, 60)

# 启动网络循环线程，在后台处理消息收发
client.loop_start()

print("Subscriber is running. Press Ctrl+C to exit.")
try:
    # 保持主线程运行
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    print("Exiting...")
    client.loop_stop()
    client.disconnect()

编写发布者脚本 publisher.py：

import paho.mqtt.client as mqtt
import time

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.connect("localhost", 1883, 60)

client.loop_start()

count = 0
try:
    while True:
        message = f"Message count: {count}"
        # 发布消息到主题 “python/test”， QoS=1
        result = client.publish("python/test", message, qos=1)
        status = result[0]
        if status == 0:
            print(f"Send `{message}` to topic `python/test`")
        else:
            print(f"Failed to send message to topic `python/test`")
        count += 1
        time.sleep(2) # 每2秒发布一次
except KeyboardInterrupt:
    print("Exiting...")
    client.loop_stop()
    client.disconnect()

运行测试：
- 在一个终端运行 python subscriber.py。
- 在另一个终端运行 python publisher.py。
- 你将在订阅者终端看到不断打印出发布的消息。

四、实际应用场景与下一步

成功在本地运行 Mosquitto 只是第一步。这个环境可以用于多种场景：

物联网设备模拟：用多个客户端脚本模拟传感器（发布温度数据）和执行器（订阅控制指令）。
移动/Web应用后端通信：作为 App 与服务器，或浏览器（通过 WebSocket）与后端服务之间的实时消息通道。
微服务间异步通信：在微服务架构中，作为轻量级的事件总线。
原型开发和测试：在将应用部署到云 MQTT 服务（如 AWS IoT Core, EMQX Cloud）之前，在本地进行完整的功能和集成测试。

安全警告：本文使用的默认配置（无认证、无加密）仅适用于本地封闭测试环境。切勿直接将此配置暴露在公网（如云服务器）上。下一步，你应该学习如何：

修改 mosquitto.conf，设置用户名/密码认证。
配置 SSL/TLS 证书，启用加密通信（端口 8883）。
使用 ACL（访问控制列表）文件精细控制客户端对主题的读写权限。

结语

通过本文的步骤，你已经成功在本地搭建了一个功能完整的 Mosquitto MQTT 消息代理环境，并掌握了使用命令行和 Python 客户端进行基本通信的方法。这为你深入探索 MQTT 协议特性（如 QoS、保留消息、遗嘱消息）和构建更复杂的物联网或实时消息应用奠定了坚实的基础。现在，就打开你的代码编辑器，开始你的 MQTT 之旅吧！

文档信息

本文作者：JiliangLee
本文链接：https://leejiliang.cn/2026/03/15/%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA%E6%89%8B%E6%8A%8A%E6%89%8B%E6%95%99%E4%BD%A0%E5%9C%A8%E6%9C%AC%E5%9C%B0%E5%AE%89%E8%A3%85%E5%B9%B6%E8%BF%90%E8%A1%8C-Mosquitto-%E4%BB%A3%E7%90%86/
版权声明：自由转载-非商用-非衍生-保持署名（创意共享3.0许可证）

CODE

物联网通信基石：手把手在本地安装并运行Mosquitto MQTT代理

物联网通信基石：手把手在本地安装并运行Mosquitto MQTT代理

一、 Mosquitto 安装指南

1. Windows 平台安装

2. macOS 平台安装

3. Linux 平台安装（以 Ubuntu/Debian 为例）

二、基础配置与运行测试

1. 使用命令行工具测试

2. 理解默认配置

三、使用 Python 客户端进行测试

四、实际应用场景与下一步

结语

文档信息

Search

Table of Contents

物联网通信基石：手把手在本地安装并运行Mosquitto MQTT代理

物联网通信基石：手把手在本地安装并运行Mosquitto MQTT代理

一、 Mosquitto 安装指南

1. Windows 平台安装

2. macOS 平台安装

3. Linux 平台安装（以 Ubuntu/Debian 为例）

二、 基础配置与运行测试

1. 使用命令行工具测试

2. 理解默认配置

三、 使用 Python 客户端进行测试

四、 实际应用场景与下一步

结语

文档信息

Search

Table of Contents

二、基础配置与运行测试

三、使用 Python 客户端进行测试

四、实际应用场景与下一步