如何用Python开发QQ机器人？

99ANYc3cd6 机器人 2025-12-06 1

这是一个非常热门且有趣的话题,最主流、功能最强大、社区最活跃的 Python QQ 机器人框架是 NoneBot2。

（图片来源网络，侵删）

下面我将为你提供一个从零开始的完整指南,包括：

为什么选择 NoneBot2？
环境准备
创建第一个机器人
编写你的第一个插件
部署与运行
进阶学习与资源

为什么选择 NoneBot2？

在开始之前,了解为什么推荐 NoneBot2 很重要：

异步驱动：基于 asyncio，性能极高，能轻松处理大量并发消息。
插件化架构：核心功能极简，所有功能都通过插件（Plugin）实现，非常灵活和可扩展。
强大的生态：拥有官方和社区开发的大量插件，可以实现签到、游戏、AI对话、群管、图床等几乎所有你能想到的功能。
跨平台适配：支持多种协议后端，最常用的是 OneBot v11，可以适配很多 QQ 客户端，如 Mirai、go-cqhttp 等。
友好的社区：文档完善，社区活跃，遇到问题容易找到解决方案。

环境准备

在开始编码之前,你需要准备好以下工具：

a. Python 环境

推荐使用 Python 3.9 或更高版本。

（图片来源网络，侵删）

# 检查你的 Python 版本
python --version
# 或
python3 --version

b. 获取 QQ 协议端

重要：由于腾讯的限制，直接使用个人号登录机器人风险很高，容易被风控，强烈建议使用协议端（如 go-cqhttp）作为桥梁。

下载 go-cqhttp：
- 前往 go-cqhttp 的 Releases 页面。
- 下载对应你操作系统的最新版本（通常是 go-cqhttp_windows_amd64.zip）。
配置和登录：
- 解压下载的文件,你会看到一个 go-cqhttp.exe (Windows) 或 go-cqhttp (Linux/Mac)。
- 首次运行：双击运行它，它会自动生成一个 config.yml 配置文件和一个 device.json 文件。
- 扫码登录：程序会弹出一个二维码，使用你的手机 QQ 扫描登录，登录成功后，程序会退出。
配置端口：
（图片来源网络，侵删）
- 打开 config.yml 文件。
- 找到 servers 部分，确保 universal 模块是启用的。
- 记下 access-token 和 ws-server 的地址和端口，通常是 0.0.0:8080，这个端口就是你 Python 机器人将要连接的地址。
```
# config.yml 示例
servers:
  - # ws 服务器设置
    ws-server: 0.0.0.0:8080
    access-token: "" # 留空即可
    ws-reverse:
      universal: ws://127.0.0.1:8080 # 这里的地址和端口要和你的机器人代码一致
      reconnect-interval: 3000
```
- 再次运行 go-cqhttp，它会保持运行，并等待你的 Python 机器人连接。

创建第一个机器人

我们来创建一个最基础的机器人项目。

a. 创建项目目录

mkdir my_qq_bot
cd my_qq_bot

b. 初始化 NoneBot 项目

使用 nb 命令行工具可以快速初始化项目。

# 安装 nb 命令行工具
pip install nb-cli
# 在项目目录下初始化
nb init

按照提示进行选择（大部分选项可以直接回车使用默认值），完成后，你的项目目录会包含以下文件：

.env: 环境变量配置文件，用于存储敏感信息。
bot.py: 机器人的主入口文件。
pyproject.toml: 项目依赖管理文件。
README.md: 项目说明文件。
src/plugins/: 存放你编写的插件。

c. 配置连接信息

打开 .env 文件，设置 ws_server_url，这个 URL 必须和你 go-cqhttp 的 ws-reverse 配置完全一致。

# .env 文件内容
WS_SERVER_URL=ws://127.0.0.1:8080 # 如果你 go-cqhttp 在本机运行
# go-cqhttp 在另一台服务器上，请填写对应的 IP 地址
# WS_SERVER_URL=ws://192.168.1.100:8080

d. 安装依赖

nb install

这个命令会读取 pyproject.toml 文件并安装所需的依赖，主要是 nonebot2 和 nonebot-adapter-onebot。

编写你的第一个插件

机器人本身没有功能,功能都在插件里，我们来创建一个最简单的“复读机”插件。

a. 创建插件文件

在 src/plugins 目录下，创建一个新文件，echo.py。

b. 编写插件代码

将以下代码写入 src/plugins/echo.py：

from nonebot import on_command
from nonebot.adapters.onebot.v11 import MessageEvent, Message
# 创建一个命令响应器
# "复读" 是命令名
# permission=None 表示所有用户都有权限使用
echo = on_command("复读", permission=None)
@echo.handle()
async def handle_echo(event: MessageEvent):
    """
    处理复读命令
    当用户发送 "复读" 时，机器人会复读用户发送的上一条消息
    """
    # 获取用户发送的消息内容（去掉命令本身）
    msg = event.get_message()
    # event.message 是 Message 对象，可以直接回复
    await echo.send(msg)

代码解释：

on_command("复读"): 创建一个命令响应器，当用户在群里输入 /复读 (或 复读) 时，这个函数就会被触发。
@echo.handle(): 这是一个装饰器，表示下面的 handle_echo 函数是处理这个命令的入口。
event: MessageEvent: 类型注解，表示 event 是一个消息事件对象。
event.get_message(): 获取用户发送的完整消息。
await echo.send(msg): 将获取到的消息发送回聊天频道。

c. 运行机器人

在项目根目录下（my_qq_bot），运行：

nb run

如果一切顺利,你会看到终端输出类似 [INFO] 的日志，表示机器人已成功连接到 go-cqhttp。

打开你的 QQ，进入一个群，发送 复读，然后紧接着发送任何内容，你的机器人就会复读你刚刚发送的内容了！

部署与运行

直接在电脑上运行 nb run 只适合开发和测试，要让机器人 24/7 在线，你需要将其部署到服务器上。

a. 使用 `screen` 或 `tmux` (推荐 Linux 服务器)

screen 是一个终端复用工具，可以让你在断开 SSH 连接后，程序依然在后台运行。

安装 screen:

# Ubuntu/Debian
sudo apt-get install screen
# CentOS/RHEL
sudo yum install screen

创建 screen 会话:
```
screen -S qq_bot
```

在 screen 会话中运行机器人:

# 进入你的项目目录
cd /path/to/my_qq_bot
# 运行机器人
nb run

断开会话: 按 Ctrl + A，然后按 D，这样你就可以安全地退出 SSH，而机器人会在后台继续运行。
重新连接会话:
```
screen -r qq_bot
```

b. 使用 Docker (更专业的方式)

对于有经验的用户,使用 Docker 是更好的选择，因为它能隔离环境，方便部署和管理。

你可以编写一个 Dockerfile 来打包你的机器人项目。

进阶学习与资源

当基础功能满足不了你时,可以探索更多高级玩法。

a. 学习 NoneBot2 核心概念

事件：理解 MessageEvent, NoticeEvent, RequestEvent 等。
指令：on_command, on_regex, on_keyword 等不同类型的指令触发方式。
响应器：Matcher 对象，用于发送消息、获取用户信息等。
依赖注入：CommandGroup, Dependent 等，用于组织复杂的插件逻辑。

b. 使用官方和社区插件

很多功能不需要自己造轮子。

官方插件：nonebot2/nonebot2/plugins
社区插件：nonebot2/nonebot2-plugin-list
插件市场：插件市场

安装一个签到插件：

# 在项目根目录执行
nb install nonebot-plugin-apscheduler

然后在 bot.py 或其他插件中导入并加载即可。

c. 探索更多适配器

除了 QQ，NoneBot2 还支持其他平台，

QQ 频道
Discord
Telegram

只需更换适配器,你就可以用一套代码为多个平台服务。

用 Python 开发 QQ 机器人是一个非常有成就感的过程，从简单的复读机，到复杂的群管系统，再到集成 AI 的智能助手，NoneBot2 为你提供了无限可能。

快速回顾步骤：

准备环境：Python + go-cqhttp。
创建项目：使用 nb init 初始化 NoneBot 项目。
配置连接：在 .env 中设置 WS_SERVER_URL。
编写插件：在 src/plugins 目录下创建 .py 文件，使用 on_command 等编写逻辑。
运行测试：使用 nb run 启动机器人进行测试。
部署上线：使用 screen 或 Docker 将机器人部署到服务器。

祝你玩得开心！如果在过程中遇到问题，可以查阅 NoneBot2 官方文档或在社区寻求帮助。

本文地址： https://www.gzrobot.org.cn/post/2103.html