1. 环境准备:搭建你的Python游乐场
嘿,朋友们,想自己动手做一个能陪你聊天、能帮你查资料、甚至能管理QQ群的智能机器人吗?听起来很酷,但会不会觉得“开发机器人”这事儿门槛太高,光是看那些框架文档就头大?别担心,我当初也是这么过来的。今天,我就带你用 NoneBot2 这个框架,从零开始,手把手打造一个属于你自己的QQ机器人。整个过程就像搭积木,我会把每一步都掰开揉碎了讲,保证你就算没写过几行代码,也能跟着做出来。
咱们这个旅程的第一步,就是准备好“施工场地”——也就是Python环境。你可以把它想象成你要盖房子,得先有一块平整的地基和合适的工具。NoneBot2是基于Python的,所以Python是我们的核心工具。这里有个关键点:Python版本必须大于等于3.9。如果你电脑上还是Python 3.7或者更老的版本,那可能就会遇到各种奇怪的兼容性问题,所以第一步就是检查并安装合适的Python。
怎么检查呢?很简单,打开你的命令行(在Windows上是“命令提示符”或“PowerShell”,在Mac或Linux上是“终端”)。输入 python --version 或者 python3 --version 看看。如果显示版本号大于等于3.9,恭喜你,可以直接进入下一步。如果没有安装,或者版本太低,就去Python官网下载最新的安装包。安装时,务必记得勾选“Add Python to PATH”这个选项,这能省去后面手动配置环境变量的一大堆麻烦事。安装好后,再在命令行里确认一下版本,确保无误。
地基打好,我们还需要一个更专业的“工具管理师”——pip。它是Python的包安装工具,我们后面安装的所有框架和依赖都要靠它。为了确保一切顺利,我们首先把它升级到最新版本。在命令行里输入:python -m pip install --upgrade pip。这个命令会让pip自己更新自己,过程通常很快。看到“Successfully installed pip-xx.x.x”这样的提示,就说明搞定了。
接下来是个稍微有点特别但非常重要的工具:pipx。你可以把它理解为一个“隔离的VIP包间”。平常我们用pip安装的Python工具,默认会放到系统的Python环境里。如果你安装的工具很多,它们之间的依赖可能会打架,导致你的开发环境一团糟。pipx的作用就是为每一个命令行工具单独创建一个干净、隔离的小环境,让它们互不干扰。安装它也只需要两行命令,还是在刚才的命令行窗口里,依次输入:
python -m pip install --user pipx
python -m pipx ensurepath
第一条命令是安装pipx本身,第二条命令是把pipx的路径添加到系统环境变量,这样你在任何地方都能直接使用它了。执行完第二条命令后,最好关闭当前命令行窗口,再重新打开一个新的。这是因为环境变量的更新需要新终端会话才能生效。这个小细节很多教程会忽略,但如果不做,下一步可能会报“命令找不到”的错误,咱们从一开始就避开这个坑。
2. 项目创建:召唤你的机器人骨架
环境工具都齐备了,是不是有点小激动?接下来就是最核心的一步——创建我们的机器人项目。这就像给你的机器人申请一个“身份证”和规划好它的“身体结构”。我们会使用NoneBot2官方提供的命令行工具 nb-cli,它是个超级好用的“脚手架”。脚手架在建筑里是临时支撑结构,在编程里,就是指能帮你快速生成项目基础代码框架的工具。
首先,我们用pipx来安装这个脚手架。打开你新启动的命令行窗口,输入:pipx install nb-cli。pipx会为nb-cli创建一个独立的运行环境并完成安装。安装成功后,你可以输入 nb --version 来验证一下,如果能看到版本号输出,那就说明一切正常。
现在,让我们为机器人项目找个“家”。你可以在电脑的任意位置新建一个文件夹,比如在D盘根目录下新建一个叫 MyQQBot 的文件夹。这个名字你可以随便起,方便自己找到就行。然后,关键的一步来了:进入这个文件夹,再在此处打开命令行。在Windows上,你可以在文件夹的地址栏里直接输入 cmd 然后回车;或者按住Shift键的同时在文件夹空白处点击鼠标右键,选择“在此处打开PowerShell窗口”。这个操作是为了确保我们后续创建的所有文件都整整齐齐地放在这个文件夹里,不会散落得到处都是。
在正确的路径下打开命令行后,输入魔法命令:nb。此时,一个交互式的创建向导会跳出来,就像玩一个文字冒险游戏,你需要做出一系列选择来塑造你的机器人。别紧张,我们一步一步来。
第一步:你想要进行什么操作? 这里当然选择“创建一个 NoneBot 项目”。
第二步:选择一个要使用的模板。
这里有两个主要选项:bootstrap 和 simple。很多老教程会推荐bootstrap,因为它更简洁,给开发者留出的自定义空间更大。但对于我们纯新手来说,我强烈推荐选择 simple 模板。为什么呢?simple模板的结构更清晰,它明确区分了“你自己写的插件”和“从商店安装的插件”的存放位置,并且默认集成了官方的插件管理功能。这能让你更直观地理解NoneBot2的插件体系,以后安装和管理第三方插件会方便得多。虽然bootstrap更自由,但初期容易让人困惑,咱们先从规矩的来。
第三步:项目名称。
给你的机器人项目起个英文名字吧,比如 my_cool_bot。注意,这里尽量只用字母、数字和下划线,不要用中文,避免后续路径出现奇怪的问题。输入名字后回车,它会自动生成一个同名文件夹。
第四步:要使用哪些适配器?
适配器是机器人和不同聊天平台(如QQ、微信、Telegram)沟通的“翻译官”。我们做QQ机器人,目前最主流、生态最成熟的是 OneBot V11 协议。所以,用方向键移动光标,按空格键选中“OneBot V11”(前面会出现一个星号*),然后回车。这里千万注意,不能直接按回车,直接回车等于没选!如果选错了,后面会有确认步骤,可以返回修改。
第五步:要使用哪些驱动器? 驱动器决定了机器人底层处理网络请求的方式。我们保持默认,选择 FastAPI 即可。这是一个高性能的现代Web框架,足够我们用了。这一步默认就是选中的,直接回车确认。
第六步:请输入插件存储位置。
这里问的是你自己编写的插件打算放在哪里。选择“在‘src’文件夹中”。这样,你的自定义插件会放在 项目名/src/plugins/ 这个路径下,和从商店安装的插件分开,非常清晰,利于管理。
第七步:立即安装依赖?
输入 Y 然后回车。依赖就是这个项目需要运行的各种第三方Python库。NoneBot2框架本身、你选的适配器和驱动器,都是一些Python包。这一步就是自动帮你把这些必需的包都下载安装好。
第八步:创建虚拟环境?
务必输入 Y 然后回车。虚拟环境是我强烈建议新手一定要用的东西。它相当于给你的这个机器人项目单独开辟了一个干净的“沙盒”。在这个沙盒里安装的库,不会影响你电脑上其他Python项目。比如,你这个机器人需要某个库的1.0版本,而你另一个项目需要2.0版本,如果没有虚拟环境,它们就会冲突。有了虚拟环境,就完全隔离了,非常安全。项目文件夹里会生成一个 .venv 的文件夹,这就是虚拟环境的所在。
第九步:选择内置插件。 内置插件是框架自带的、用于测试和体验功能的小插件。我们用方向键移动,按空格键选中“echo”(复读机插件)。这个插件会让机器人重复你说的话,是我们测试机器人是否“活”了的最简单工具。同样,记得是按空格选择,不是回车。
完成所有选择后,脚手架就会开始忙碌,下载各种包并创建项目结构。当你看到“项目创建成功!”之类的提示,并且命令行回到了可输入状态,就大功告成了!现在,你可以去刚才的 MyQQBot 文件夹里看看,里面应该多了一个以你项目名命名的文件夹(比如 my_cool_bot),这就是你机器人的“身体”了。
3. 协议端配置:给机器人注入灵魂
项目骨架有了,但现在的机器人还是个“植物人”,没有意识,也无法连接到QQ。接下来,我们要给它注入灵魂——让它能登录一个QQ号,并接收和发送消息。这就需要用到“协议端”,或者叫“客户端”。你可以把它理解成机器人的“手机”,NoneBot2框架是它的大脑,而协议端就是它用来登录QQ、收发消息的硬件设备。
目前,在OneBot V11协议下,有几个比较流行的协议端选择,比如 Lagrange、LLOneBot 等。它们本质上都是一个实现了OneBot V11协议的程序,负责和腾讯的服务器通信。这里我以 Lagrange 为例,因为它对新手比较友好,图形化界面清晰。
首先,你需要去Lagrange的GitHub发布页面下载最新版本的压缩包。下载完成后,解压到一个你方便找到的目录,比如 D:\Lagrange。进入解压后的文件夹,你应该能看到一个名为 lagrange.exe 的可执行文件(Windows系统)。在运行它之前,我们还需要进行一个关键的配置:修改NoneBot2项目的配置文件,让大脑知道“手机”在哪里。
回到你的机器人项目文件夹,找到 my_cool_bot 目录,里面有一个重要的文件叫 .env.prod(如果没看到,可能是隐藏文件,需要在文件管理器设置中显示隐藏文件)。用记事本或任何代码编辑器打开它。我们需要在里面添加一行配置,告诉机器人协议端(也就是Lagrange)的连接信息:
ONEBOT_WS_URLS=ws://127.0.0.1:8080/onebot/v11/ws
这行配置的意思是:通过WebSocket协议,连接到本机(127.0.0.1)的8080端口,路径是 /onebot/v11/ws。这是Lagrange默认的通信地址。保存并关闭这个文件。
现在,双击运行 lagrange.exe。第一次运行,它会让你登录QQ。这里极其重要:请务必使用一个不常用的小号! 因为腾讯的用户协议并不允许自动化登录和操作,存在账号被风控甚至封禁的风险。用小号可以避免损失。登录成功后,你需要进入Lagrange的设置界面,找到“OneBot服务”或类似的设置项。确保其“WebSocket服务器”是启用状态,并且监听的地址和端口与我们刚才在 .env.prod 里配置的一致(通常是 0.0.0.0:8080)。这样,协议端就准备就绪,在8080端口上等待我们机器人大脑的连接了。
4. 运行与测试:见证机器人诞生
最激动人心的时刻到了!我们要启动机器人,并测试它是否真的能工作。确保你的Lagrange协议端已经登录并保持运行,那个窗口不能关。
然后,我们回到机器人项目。打开命令行,导航到你的项目根目录,也就是 my_cool_bot 这个文件夹里面。在这个路径下,输入启动命令:
nb run
你会看到命令行开始刷出一大堆日志信息,这是机器人在启动加载各种模块。当你看到类似“Running on http://127.0.0.1:8080”、“Application startup complete”这样的提示时,就说明你的NoneBot2机器人框架已经成功启动,并且应该已经通过WebSocket连接上了Lagrange协议端。
现在,让我们进行第一次对话测试。打开你的QQ,用另一个号(或者就用你登录Lagrange的小号本身)给这个机器人小号发一条私聊消息。还记得我们创建项目时选的 echo 插件吗?它的触发方式是:在私聊中,发送 /echo 你想说的话。比如,你发送:
/echo 你好,世界!
如果一切配置正确,你的机器人小号应该会立刻回复一条一模一样的“你好,世界!”消息。看到这个回复的瞬间,感觉是不是很棒?这意味着你的机器人已经成功接收、处理并响应了消息,整个链路完全打通了!
如果在群里测试,格式稍有不同,需要 @机器人。比如在群里发送:
/echo 测试一下 @你的机器人昵称
同样,机器人应该会复读“测试一下”。这个简单的测试验证了从消息接收、框架处理、插件执行到消息发送的完整流程。如果测试失败,别慌,首先检查:1. Lagrange是否在线;2. .env.prod 配置是否正确;3. 运行 nb run 的命令行是否有明显的红色错误日志。根据错误信息去搜索,大部分初期问题都能找到解决方案。
5. 项目结构解析:看懂机器人的五脏六腑
机器人跑起来了,我们再来回头仔细看看脚手架为我们生成的这一堆文件和文件夹,它们各自是干什么的。了解清楚结构,以后开发插件、修改配置、排查问题才能得心应手。我们进入 my_cool_bot 项目目录,来一次深度游。
pyproject.toml: 这是项目的核心配置文件,相当于机器人的“身份证”和“需求清单”。里面定义了项目名称、版本、依赖的Python包及其版本。以后如果你想安装新的插件或库,很多都可以通过修改这个文件或者用nb plugin install命令来完成。.env与.env.prod: 环境配置文件。.env通常用于开发环境,.env.prod用于生产环境。我们之前修改的就是.env.prod。这里可以存放各种敏感或可变的配置,比如机器人监听的端口、数据库连接地址、各种API密钥等。切记不要将包含密码或密钥的.env文件上传到Git等公开仓库!bot.py: 这是机器人的主程序入口文件。当你运行nb run时,本质上就是启动了这个Python文件。它负责初始化NoneBot2实例、加载配置、注册适配器和插件。初期我们一般不需要改动它。src/目录: 这是我们自己编写插件的“自留地”。脚手架建议我们把自定义插件放在src/plugins/目录下。比如你可以创建一个src/plugins/weather/文件夹,里面放一个__init__.py文件,就能开始编写一个查询天气的插件了。这种结构非常清晰。.venv/目录: 这就是之前创建的Python虚拟环境。所有为这个项目安装的第三方库(比如nonebot2、fastapi等)都存放在这里。你从官方插件商店安装的插件,其代码实际也会安装到这个目录下的site-packages文件夹里,通常以nonebot_plugin_开头。注意:你自己写的插件放在src/,商店安装的插件在.venv里,这是两个不同的地方,别搞混了。- 其他配置文件: 比如
docker-compose.yml(用于容器化部署)、alembic.ini(数据库迁移工具配置)等,在初期我们可以先不用管。
理解了这个结构,你就能明白为什么推荐 simple 模板了。它把“自己写的”和“外部安装的”分得清清楚楚,项目目录干净利落。当你未来想分享自己的插件时,你只需要打包 src/plugins/ 里的东西;当你从商店安装了一个好玩的插件,你也知道该去哪里找它的源码参考学习(在 .venv/lib/site-packages/ 里)。
6. 编写第一个自定义插件:让机器人真正为你所用
只会复读的机器人显然不够看。现在,我们来亲手为它添加第一个自定义功能,比如一个简单的“今日运势”插件。这将让你真正理解NoneBot2插件的工作原理。
首先,在 src/plugins/ 目录下,新建一个文件夹,命名为 fortune_telling。然后,在这个文件夹里创建一个 __init__.py 文件(注意,必须是这个文件名)。用代码编辑器打开这个文件,我们将开始编写代码。
一个最基本的NoneBot2插件通常包含以下几个部分:
- 导入必要的模块。
- 创建一个“命令处理器”,并定义触发命令的规则。
- 编写处理函数,实现具体的逻辑。
- 将处理函数注册到机器人。
我们来写一个简单的运势插件,当用户发送“/运势”时,机器人随机回复一句吉祥话。将以下代码复制到 __init__.py 中:
import random
from nonebot.plugin import on_command
from nonebot.adapters.onebot.v11 import Message, MessageSegment
from nonebot.params import CommandArg
# 创建一个命令处理器,触发关键词是“运势”,别名可以是“占卜”、“运气”
fortune = on_command("运势", aliases={"占卜", "运气"}, priority=10, block=True)
# 定义一些随机的运势语句
fortune_texts = [
"大吉!今天你是幸运之星,诸事皆宜!",
"中吉!平稳的一天,可能会有小惊喜哦。",
"小吉!按部就班就好,注意细节。",
"末吉!稍微需要一点耐心,好事多磨。",
"平!普普通通的一天,享受平静吧。",
"凶!今天可能有点小波折,但保持乐观总能度过!"
]
@fortune.handle()
async def handle_fortune(args: Message = CommandArg()):
# 随机选择一条运势
reply_text = random.choice(fortune_texts)
# 发送回复。MessageSegment.text()用于构造纯文本消息
await fortune.finish(MessageSegment.text(reply_text))
保存文件后,神奇的事情发生了:你不需要重启整个机器人程序。NoneBot2支持“热重载”,对于 src/plugins/ 目录下的插件,它会自动检测文件变化。你只需要回到运行 nb run 的命令行窗口,应该能看到它自动重新加载了插件。现在,去QQ里对你的机器人发送“/运势”,看看它会回复什么?多试几次,每次回复应该是随机的。
让我解释一下这段代码:
on_command("运势", ...):这创建了一个命令处理器。当用户消息以“/运势”、“/占卜”或“/运气”开头时(命令前缀默认为/),就会触发这个插件。priority=10:是处理器的优先级,数字越大优先级越高,当多个插件可能响应同一条消息时,优先级高的先执行。block=True:表示这个处理器处理完消息后,阻止后续其他低优先级的处理器再处理这条消息。handle()装饰器:下面的handle_fortune函数就是真正的处理函数。CommandArg():用于获取用户跟在命令后面的参数。比如“/运势 白羊座”,这里我们没用到这个参数。fortune.finish():这是结束处理并发送回复的方法。我们用它发送了一条随机选择的文本消息。
通过这个简单的例子,你已经掌握了编写插件的核心流程。你可以依葫芦画瓢,修改触发词、增加更复杂的逻辑(比如调用网络API查询天气、查股票)、甚至发送图片(使用 MessageSegment.image())等等。插件的世界就此打开。
7. 进阶配置与插件管理:打造功能丰富的机器人
基础功能会了,我们来看看如何让机器人变得更强大、更易管理。这主要涉及两方面:深入配置和安装第三方插件。
首先,关于配置。 我们之前只接触了 .env.prod 里的一个配置。实际上,NoneBot2的配置非常灵活。你可以在项目根目录创建一个 config 文件夹,里面放不同的配置文件。但更常见的是直接修改 pyproject.toml 文件中的 [tool.nonebot] 部分。比如,你可以修改默认的命令前缀:
[tool.nonebot]
command_start = ["/", ""] # 命令前缀可以是“/”或者无前缀(仅匹配纯命令词)
command_sep = [".", "/"] # 命令分隔符,用于二级命令,如“/天气.北京”
这样设置后,除了“/运势”,直接发“运势”也能触发我们的插件了。配置项还有很多,比如设置超级用户(管理员)、配置数据库连接、调整日志级别等,这些都可以在官方文档的“配置”章节找到详细说明。
其次,是强大的插件生态。 NoneBot2有一个官方的插件商店,里面有成百上千个社区开发者贡献的插件,可以实现复读、签到、游戏、音乐、AI聊天、资源查询等无数功能。安装它们非常简单,不需要手动下载代码。在项目根目录下,使用nb-cli命令即可。例如,我想安装一个著名的“表情包制作”插件:
nb plugin install nonebot-plugin-memes
执行这个命令后,nb-cli会自动从插件商店找到这个插件,下载并安装到当前项目的虚拟环境中(也就是 .venv 目录里)。安装完成后,通常还需要在 .env.prod 或配置文件中进行一些简单的配置(比如API密钥,如果需要的话)。然后重启机器人(在 nb run 的命令行按 Ctrl+C 停止,再重新运行 nb run),新插件就生效了。你可以用 nb plugin list 查看已安装的插件。
管理自己编写的插件也同样方便。当你 src/plugins/ 下的插件越来越多,你可以通过 nb plugin export 命令将它们打包,分享给其他人。整个插件体系的设计,让功能的扩展变得像搭积木一样简单。
8. 常见问题与避坑指南
一路做下来,你可能已经成功了,也可能遇到了一些小麻烦。这里我集中总结几个新手最容易“踩坑”的地方,以及我的解决经验。
问题一:运行 nb run 时报错,提示找不到模块或版本冲突。
这通常是虚拟环境没激活或者依赖安装不全导致的。首先确保你是在项目根目录(有 pyproject.toml 的目录)下运行的命令。其次,可以尝试手动重新安装依赖:pip install -e .(注意命令最后有个点)。如果还不行,检查Python版本是否>=3.9,以及pip是否已更新到最新。
问题二:机器人能启动,但收不到消息或发不出消息。 99%的问题出在协议端(Lagrange)和NoneBot2的连接配置上。
- 双重检查
.env.prod文件:确保ONEBOT_WS_URLS的地址和端口与Lagrange设置中的WebSocket服务器地址完全一致。Lagrange默认是0.0.0.0:8080,那么配置就应该是ws://127.0.0.1:8080/...。 - 检查防火墙:有时候Windows防火墙会阻止本地端口通信。可以尝试临时关闭防火墙测试,或者添加一个入站规则允许8080端口。
- 查看日志:
nb run的日志和Lagrange的日志窗口都含有黄金信息。注意看是否有“Connection established”或“WebSocket连接成功”的字样。如果有连接错误,日志会明确告诉你。
问题三:插件写了,但发送命令没反应。
- 检查插件加载:启动机器人时,日志里应该有一行类似“Loaded plugin
fortune_tellingfromsrc.plugins.fortune_telling”的信息。如果没有,说明插件没被正确识别。检查__init__.py的文件名和路径是否正确,以及代码是否有语法错误。 - 检查命令前缀和触发词:确认你发送的消息格式符合
command_start和命令词的组合。默认是/运势。你也可以在日志里开启调试信息,看看机器人到底有没有收到你的消息。
问题四:想更新或卸载插件怎么办?
对于从商店安装的插件,可以使用 nb plugin update <插件名> 来更新,用 nb plugin uninstall <插件名> 来卸载。对于自己写的 src/plugins/ 下的插件,直接删除或修改那个文件夹里的文件即可。
最后,也是最重要的提醒:请务必使用QQ小号! 自动化操作存在风险,不要用你的大号、主号来运行机器人。将机器人用于学习和娱乐即可,避免高频、重复、营销类消息发送,这样可以最大程度降低风险。玩得开心,也要玩得安心。
748



被折叠的 条评论
为什么被折叠?



