从零部署 QQ 机器人：NapCat + NoneBot2 完整指南

基于 OneBot v11 协议，构建一个可以通过插件支持多样化功能的 QQ 机器人。
本文作为基础篇，将从 NapCat 协议端的部署、NoneBot2 框架的搭建到第一个测试插件的编写——为你挨个讲解。

---

📌 目录

• 从零部署 QQ 机器人：NapCat + NoneBot2 完整指南
  • 📌 目录
  • 一、架构总览
  • 二、通信原理
    • 2.1 两种 WebSocket 连接方式
    • 2.2 为什么推荐反向 WebSocket？
    • 2.3 数据流向示意
  • 三、环境准备
  • 四、部署 NapCat 协议端
    • 4.1 扫码登录
    • 4.2 配置 WebSocket 反向连接
  • 五、部署 NoneBot2 框架
    • 5.1 虚拟环境
    • 5.2 安装NoneBot2脚手架及相关依赖
    • 5.3 配置环境变量
    • 5.4 启动顺序重要说明
    • 5.5 启动机器人
  • 六、编写第一个测试插件
    • 6.1 插件目录结构
    • 6.2 编写插件代码
    • 6.3 配置插件加载
    • 6.4 测试插件
    • 6.5 进阶：实现真正的 Echo 功能
    • 6.6 常见问题排查
  • 七、总结与下章预告
    • 7.1 本文总结
    • 7.2 预告
    • 7.3 参考链接

---

一、架构总览

组件	作用	关键特性	选择原因
NapCat	基于 NTQQ 协议的无头框架	轻量级、资源占用低	针对新版QQ协议持续更新
	提供 OneBot v11 标准接口	无头模式、易于集成	社区响应快
NoneBot2	Python 异步机器人框架	全异步支持、丰富插件生态	可定制性强，文档完善
	采用插件化架构	事件驱动	中文文档详尽

---

二、通信原理

在开始部署之前，先理解 NapCat 和 NoneBot2 之间的通信方式，有助于你后续排查问题和扩展架构。

点击 这里 跳转到部署章节。

2.1 两种 WebSocket 连接方式

OneBot v11 协议支持两种 WebSocket 连接模式：

模式	连接方向	说明	适用场景
正向 WebSocket	NoneBot → NapCat	NoneBot 作为客户端	NapCat 先启动并监听端口
	主动连接 NapCat
反向 WebSocket	NapCat → NoneBot	NapCat 作为客户端	NoneBot 先启动并监听端口
	主动连接 NoneBot

2.2 为什么推荐反向 WebSocket？

本文采用的是反向 WebSocket 客户端模式（NapCat 作为客户端连接NoneBot），原因如下：

1. NoneBot 作为服务核心，稳定性更高
NoneBot 是机器人的逻辑处理中心，通常需要先启动并持续运行。让 NapCat 主动连接 NoneBot，可以确保：

• NoneBot 重启后，NapCat 会自动重连
• NapCat 掉线后，NoneBot 无需重启，等待 NapCat 重新连接即可

2. 更自然的故障恢复机制
NapCat 作为客户端，内置了重连机制（默认30秒重连一次）。当网络波动或 NoneBot 重启时：

NoneBot 重启 → 开始监听端口
    ↓
NapCat 检测到连接断开 → 30秒后自动重连
    ↓
重新建立连接 → 机器人恢复正常工作

整个过程无需人工干预，可以自动故障恢复。

3. 便于多实例扩展
如果你需要运行多个 QQ 账号（多个 NapCat 实例），反向 WebSocket 模式下：

• NoneBot 只需启动一个监听端口
• 多个 NapCat 实例分别连接到同一个 NoneBot
• 无需为每个 NapCat 配置不同的端口

2.3 数据流向示意

---

三、环境准备

建议把 NapCat 和 NoneBot2 都部署在同一台电脑或者服务器上，以此提供稳定的 QQbot 服务。该篇旨在"从零部署"，所以以 Windows 系统为例。

提示：本文以 Windows 环境为例讲解，Linux/macOS 用户可参阅底部的参考文档。

在开始部署之前，请准备以下环境：

环境	版本/要求	用途	是否必需
Python	3.12 或以上	运行 NoneBot2 机器人框架	必需
Git	任意版本	克隆项目代码（也可手动下载zip压缩包）	可选
NapCat	最新版本	QQ 协议端，提供 OneBot v11 接口	必需
QQ 账号	非主号、非新号	用于运行机器人	必需
NoneBot2	随项目一步一步安装	机器人框架，处理消息和插件管理	必需

提示：所有环境部署在同一台设备上，WebSocket 即可使用 127.0.0.1，无需额外网络配置。

以下为基础环境安装步骤，属于通用操作，此处不再赘述。请参考官方文档完成安装：

环境	下载网址	参考文档
Python	Python 官网	Python 官方下载文档
NapCat	NapCat Win版一键安装	NapCat 安装指南
Git	Git 官方下载页	Git 下载逐页翻译参考

---

四、部署 NapCat 协议端

NapCat 是基于 NTQQ 协议的轻量级 Headless 框架，资源占用低，是当前搭建QQ机器人的不二之选。下文仅为步骤简述，不展开细节。

在安装指南的后文有详细的配置教程，可以参考并配置。

4.1 扫码登录

完成 NapCat 安装后，接下来需要进行 QQ 账号登录：

1.启动 NapCat
打开 NapCat 安装目录，双击运行 launcher.bat 这是适用于 Win11 的 NapCat 启动脚本。

2.获取登录二维码
程序启动后，会自动显示登录二维码。此时有两种方式可以扫码：

• 方式一（推荐）：如果控制台窗口正常显示二维码，直接使用手机 QQ 扫描即可。
• 方式二（备选）：如果控制台出现乱码或未显示二维码，可以按住 Ctrl 键并点击终端中显示的 WebUI 网址（如图中箭头所示），在浏览器中打开NapCat管理面板进行扫码。
  完成 NapCat 安装后，接下来需要进行 QQ 账号登录：

1.启动 NapCat
打开 NapCat 安装目录，双击运行 launcher.bat 这是适用于 Win11 的 NapCat 启动脚本。

2.获取登录二维码
程序启动后，会自动显示登录二维码。此时有两种方式可以扫码：

• 方式一（推荐）：如果控制台窗口正常显示二维码，直接使用手机 QQ 扫描即可。
• 方式二（备选）：如果控制台出现乱码或未显示二维码，可以按住 Ctrl 键并点击终端中显示的 WebUI 网址（如图中箭头所示），在浏览器中打开NapCat管理面板进行扫码。
  

3.扫码登录
打开手机 QQ，使用"扫一扫"功能扫描控制台或 WebUI 中的二维码，完成账号登录。

4.配置快速登录（可选）
登录成功后，建议在 WebUI 面板中配置快速登录账号。这样下次启动 NapCat 时，无需再次扫码即可自动登录。

注意事项：

• 建议使用有正常使用记录的 QQ 账号，现创的新号或长期未使用的账号大概率触发风控
• 避免频繁扫码或切换设备，以免被限制登录
• 如果登录失败，可以先在 QQ 手机端或客户端登录一段时间，再尝试登陆 NapCat
  

4.2 配置 WebSocket 反向连接

登录成功后，进入 WebUI 面板进行网络配置：

配置说明：

配置项	推荐值	说明
名称	NoneBot2	自定义标识名称
URL	ws://127.0.0.1:8080/onebot/v11/ws	同一台电脑使用 127.0.0.1
		端口与 NoneBot2 一致
消息格式	Array	推荐格式
心跳间隔	30000	30 秒
重连间隔	30000	30 秒
Token	自定义强密码	务必妥善保管，后续需在 .env 中填写

配置完成后，点击右下角保存按钮即可。NapCat 会主动连接到 NoneBot2 框架。

• 记下这些值，尤其是 Token，后面配置 NoneBot2 时会用到。如果留空后续可以不填。
• 前文提到 NapCat 与 NoneBot 尽量运行在同一台机器，就是为了方便 WebSocket 连接地址可以使用 127.0.0.1，减少额外的网络配置。

接下来搭建 NoneBot2，可以先关闭 NatCat，避免如下报错。

---

五、部署 NoneBot2 框架

NoneBot2因其优雅的异步框架和丰富的插件生态成为我们搭建QQ机器人的首选。

下面操作均基于Python虚拟环境，确保依赖隔离与项目整洁。

建议在VS Code的集成终端中操作，后续交互选项可以直接用鼠标勾选

5.1 虚拟环境

• 创建
  在项目根目录下创建并激活虚拟环境（以QQbot为例）：

mkdir QQbot
cd QQbot
python -m venv .venv

• 激活

# powershell：
.venv\Scripts\Activate.ps1
# cmd：
.venv\Scripts\activate.bat

激活后，命令行前缀会出现 (.venv)。

5.2 安装NoneBot2脚手架及相关依赖

• 安装脚手架工具

pip install nb-cli

nb-cli是NoneBot2的命令行管理工具，用于创建项目、管理插件、运行机器人。

• 创建NoneBot2项目

执行以下命令并根据提示进行选择：

nb create

交互式选项参考：

• 项目模板 (Project Template)：选择 bootstrap（初学者推荐）
• 项目名称 (Project Name)：输入 QQbot
• 适配器 (Adapters)：使用空格键选择 OneBot V11 适配器
• 驱动器 (Driver)：默认 FastAPI 即可
• 其他选项：直接回车使用默认值

创建完成后，项目结构如下：

QQbot/
├── .env                    # 环境变量配置文件
├── pyproject.toml          # 项目元数据及依赖
├── bot.py                  # 机器人入口文件
├── src/
│   └── plugins/            # 插件存放目录

• 安装项目依赖

注意：nb create 会自动生成 pyproject.toml，其中已声明了核心依赖，但实际运行前需要安装它们。

进入项目目录，使用 pip 安装依赖：

cd QQbot
pip install -e .

或者你也可以直接使用 nb-cli 安装所需适配器与驱动器（创建时已选好，但手动安装可确保版本正确）：

pip install nonebot2[fastapi] nonebot-adapter-onebot

安装完成后，可以使用以下命令检查依赖是否就绪：

pip list | findstr nonebot

5.3 配置环境变量

在项目根目录的 .env 文件（没有则新建）中添加：

# 环境标识 (dev / prod)
ENVIRONMENT=dev

# NoneBot 驱动
DRIVER=~fastapi

# OneBot WebSocket 配置（监听 NapCat 的连接）
ONEBOT_ACCESS_TOKEN=你的Token（与NapCat中设置的一致，如果未设置就不写）

说明：反向 WebSocket 模式下，NoneBot2 默认监听
ws://127.0.0.1:8080/onebot/v11/ws ，因此无需额外配置
ONEBOT_WS_SERVER。如果你将来需要修改端口，可以添加:

ONEBOT_WS_SERVER = "ws://127.0.0.1:你的端口/onebot/v11/ws"

5.4 启动顺序重要说明

由于我们使用的是反向 WebSocket
（NapCat 作为客户端连接 NoneBot2），
必须确保 NoneBot2 先启动并开始监听端口，
然后再启动 NapCat
（或 NapCat 自动尝试重连）。

正确的操作流程：

• 先执行 nb run 启动 NoneBot2
• 确认 NoneBot2 日志显示 Running on 127.0.0.1:8080
• 再启动 NapCat（运行 launcher.bat）

如果顺序颠倒，NapCat 会因无法连接而报错，但它的自动重连机制会在 30 秒后再次尝试，所以即便先启动了 NapCat，稍后启动 NoneBot2 也能自动连上。建议按上述顺序操作。

5.5 启动机器人

第一次创建完成后，推荐使用热重载模式运行（方便调试）：

nb run --reload

如果只是平时运行，使用以下命令即可：

nb run

打开 NoneBot2 后，再运行 launcher.bat 启动 NapCat，等待它们自动连接。

成功标志：当你在命令行看到类似以下日志即表示启动成功：

---

六、编写第一个测试插件

部署完成后，接下来编写第一个插件来验证整个系统是否正常工作。我们将创建一个简单的 /hello 命令插件。

6.1 插件目录结构

NoneBot2 的插件存放在 src/plugins/ 目录下，每个插件是一个独立的文件夹。首先创建 echo 插件的目录结构：

QQbot/
├── src/
│   └── plugins/
│       └── echo/
│           └── __init__.py    # 插件主文件

在项目根目录下执行以下命令创建插件目录：

# 创建 echo 插件文件夹
mkdir src\plugins\echo

然后在该文件夹中创建 __init__.py 文件（这是 Python 的模块标识文件，NoneBot2 会自动扫描并加载它）。

6.2 编写插件代码

使用你喜欢的编辑器（如 VS Code）打开 src/plugins/echo/__init__.py，输入以下代码：

from nonebot import on_command
from nonebot.adapters.onebot.v11 import Bot, Event

# 当用户发送 "/hello" 时触发
hello = on_command("hello")

# 处理这个命令
@hello.handle()
async def handle_hello(bot: Bot, event: Event):
    # 回复用户
    await hello.finish("我喜欢你！")

代码解析：

代码	说明
from nonebot import on_command	导入命令匹配器
	用于监听特定命令
from nonebot.adapters.onebot.v11 import Bot, Event	导入 OneBot V11 适配器
	的 Bot 和 Event 对象
hello = on_command("hello")	创建一个命令匹配器
	监听 /hello 命令
	（NoneBot2 默认命令前缀为 /）
@hello.handle()	装饰器，注册命令的处理函数
await hello.finish("...")	发送回复消息并结束处理流程

提示：这个插件虽然命名为 “echo”，
但实际实现的是一个 /hello 命令，
用于测试插件系统是否正常工作。
后续你可以将其改造成真正的 echo 功能
（回显用户输入）。

6.3 配置插件加载

NoneBot2 通过 pyproject.toml 文件中的配置自动加载插件。打开项目根目录下的 pyproject.toml，确保包含以下内容：

[tool.nonebot]
plugin_dirs = ["src/plugins"]

这告诉 NoneBot2 从 src/plugins 目录加载所有插件。如果你的项目是通过 nb create 创建的，这个配置通常已经默认存在。

6.4 测试插件

完成以上步骤后，按以下顺序操作：

1. 重启 NoneBot2
如果 NoneBot2 已经在运行，按下 Ctrl+C 停止它，然后重新启动：

nb run --reload

使用 --reload 参数可以启用热重载模式，修改代码后会自动重新加载，无需手动重启。

2. 启动 NapCat
运行 launcher.bat 启动 NapCat，等待它自动连接到 NoneBot2。

3. 发送测试消息
用你的 QQ 账号向机器人发送以下消息：

/hello

4. 预期响应
如果一切正常，机器人会回复：

我喜欢你！

同时在 NoneBot2 的控制台你会看到类似以下的日志：

[SUCCESS] nonebot | Event will be handled by Matcher(type='message', module=src.plugins.echo)
[INFO] nonebot | Matcher run complete

6.5 进阶：实现真正的 Echo 功能

如果你想实现一个真正的 echo 功能（回显用户输入的内容），可以参考以下代码：

from nonebot import on_command
from nonebot.adapters.onebot.v11 import Bot, Event, Message

# 创建 echo 命令匹配器
echo = on_command("echo")

@echo.handle()
async def handle_echo(bot: Bot, event: Event):
    # 获取用户输入的纯文本（去除命令本身）
    message = event.get_plaintext()
    # 去掉 "/echo " 前缀，只保留用户输入的内容
    if message.startswith("echo "):
        text = message[5:]
    else:
        text = message
    # 回显用户输入
    await echo.finish(Message(text))

使用方式：发送 /echo 你好世界，机器人会回复 你好世界。

新增的关键方法：

方法	说明
event.get_plaintext()	获取事件的纯文本内容
Message(text)	创建 Message 对象，可以发送文本消息

6.6 常见问题排查

问题	可能原因	解决方法
发送 /hello 无响应	插件未被加载	检查 pyproject.toml 中的 plugin_dirs 配置
控制台报错 ModuleNotFoundError	缺少 __init__.py 文件	确保插件文件夹内有此文件
机器人回复乱码	文件编码问题	确保 __init__.py 使用 UTF-8 编码保存
命令前缀不是 /	命令配置被修改	检查 .env 文件中是否有 COMMAND_START 配置

---

七、总结与下章预告

7.1 本文总结

通过本指南，你已完成以下内容：

阶段	完成情况	说明
NapCat Win版本部署与登录	✅	解压即用，无需 Docker
NoneBot2 框架的搭建	✅	插件化架构，易于扩展
WebSocket 反向连接配置	✅	实现稳定通信与自动重连
编写并测试第一个插件	✅	验证部署成功，具备扩展基础

至此，一个基础的 QQ 机器人已经可以正常运行，你可以基于此框架自由开发各类功能插件。

7.2 预告

接下来，我们依次实现：

• 接入 DeepSeek API 实现 AI 对话（含猫娘人设与记忆管理）
• 群聊趣味互动功能开发
• 插件模块化组织与配置管理
• 开机自启与后台运行优化

7.3 参考链接

• NapCat 官方文档
• NoneBot2 文档
• OneBot v11 协议

---

如果你在部署过程中遇到问题，欢迎在评论区留言交流！