大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



---

• 从零部署 机器人：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 和 NoneBot2 之间的通信方式，有助于你后续排查问题和扩展架构。

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

2.1 两种 WebSocket 连接方式

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

2.2 为什么推荐反向 WebSocket？

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

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

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

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

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

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

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

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

2.3 数据流向示意

---

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

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

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

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

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

---

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

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

4.1 扫码登录

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

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

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

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

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

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

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

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

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

注意事项：

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

4.2 配置 WebSocket 反向连接

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

配置说明：

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

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

---

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

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

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

5.1 虚拟环境

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

mkdir bot cd bot python -m venv .venv 

• 激活

# powershell： .venvScriptsActivate.ps1 # cmd： .venvScriptsactivate.bat 

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

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

• 安装脚手架工具

pip install nb-cli 

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

• 创建NoneBot2项目

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

nb create 

交互式选项参考：

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

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

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

• 安装项目依赖

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

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

cd bot 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中设置的一致，如果未设置就不写） 

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

5.4 启动顺序重要说明

正确的操作流程：

• 先执行 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 插件的目录结构：

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

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

# 创建 echo 插件文件夹 mkdir srcpluginsecho 

然后在该文件夹中创建 __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("我喜欢你！") 

代码解析：

提示：这个插件虽然命名为 “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. 发送测试消息
用你的 账号向机器人发送以下消息：

/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 你好世界，机器人会回复 你好世界。

新增的关键方法：

6.6 常见问题排查

---

7.1 本文总结

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

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

7.2 预告

接下来，我们依次实现：

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

7.3 参考链接

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

---

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