NoneBot 入门指南：从零开始搭建QQ机器人

前言

NoneBot 是一个基于 Python 的异步 QQ 机器人框架，它可以帮助开发者快速构建功能丰富的聊天机器人。本文将带领你完成 NoneBot 的最小实例搭建，实现你的第一个机器人对话。

环境准备

在开始之前，请确保你已经完成以下准备工作：

1. 安装 Python 3.7+ 环境
2. 安装 NoneBot 框架
3. 配置好 QQ 机器人客户端

创建最小实例

让我们从一个最简单的 NoneBot 实例开始。创建一个名为 bot.py 的文件，内容如下：

import nonebot

if __name__ == '__main__':
    nonebot.init()
    nonebot.load_builtin_plugins()
    nonebot.run(host='127.0.0.1', port=8080)

这段代码做了三件事：

1. nonebot.init() - 使用默认配置初始化 NoneBot
2. nonebot.load_builtin_plugins() - 加载内置插件
3. nonebot.run() - 启动服务，监听指定地址和端口

关于监听地址的说明

host='127.0.0.1' 表示只监听本地回环地址。如果你的 QQ 客户端运行在其他位置（如 Docker 容器或局域网其他机器），需要修改为：

• 0.0.0.0 监听所有网络接口
• 或者指定具体的 IP 地址

启动机器人

在命令行中执行以下命令启动机器人：

python bot.py

成功启动后，你将看到类似如下的日志输出：

[时间戳] INFO: Succeeded to import "nonebot.plugins.base"
[时间戳] INFO: Running on 127.0.0.1:8080
 * Serving Quart app ''
 * Environment: production
 * Please use an ASGI server (e.g. Hypercorn) directly in production
 * Debug mode: True
 * Running on http://127.0.0.1:8080 (CTRL + C to quit)
[时间戳] INFO: Scheduler started

配置 QQ 客户端

要让 QQ 客户端与 NoneBot 通信，需要配置反向 WebSocket 连接。修改 QQ 客户端的配置文件：

servers:
  - ws-reverse:
      universal: ws://127.0.0.1:8080/ws/

重要提示：

• 这里的地址必须与 nonebot.run() 中的配置一致
• 如果 NoneBot 监听 0.0.0.0，这里应填写实际可访问的 IP
• 协议前缀必须是 ws:// 而不是 http://

特殊环境配置

对于 Docker 等容器化环境：

• Linux 宿主机：通常使用 172.17.0.1
• macOS/Windows：可使用 host.docker.internal

验证连接

成功连接后，NoneBot 控制台会显示 WebSocket 连接日志：

[时间戳] 127.0.0.1:端口号 GET /ws/ 1.1 101 - 响应时间

第一次对话

现在可以向你的机器人发送测试消息了：

/echo 你好，世界

如果一切正常，机器人会回复相同的消息："你好，世界"。这表示你的 NoneBot 实例已经成功运行！

常见问题排查

如果连接不成功，请检查以下方面：

1. 网络连通性：确保 IP 和端口可访问
2. 端口冲突：检查端口是否被其他程序占用
3. 协议正确性：确认使用 ws:// 协议
4. 防火墙设置：确保端口未被防火墙阻止
5. 配置一致性：NoneBot 和客户端的配置要匹配

下一步

现在你已经成功搭建了最小 NoneBot 实例，接下来可以：

1. 探索更多内置插件功能
2. 学习如何开发自定义插件
3. 了解 NoneBot 的配置系统和插件机制

NoneBot 提供了丰富的功能和灵活的扩展方式，让你可以构建各种复杂的机器人应用。祝你在 QQ 机器人开发之旅中收获满满！