用 Python 写跨平台聊天机器人（NoneBot2）

同一套机器人功能要在 QQ、Telegram、飞书、钉钉几个平台上都用，常见做法是每个平台单独写一份逻辑，协议一改就得跟着重写。NoneBot2 把平台差异收进适配器，业务逻辑集中到插件里，换平台时的改动集中在配置层。

NoneBot2 是用 Python 写的异步聊天机器人框架，把 QQ、Telegram、飞书、钉钉等平台的消息统一成事件，交给插件处理并回复。

项目由 nonebot 组织维护，2020 年 8 月 23 日创建，最近一次提交在 2026 年 10 月 2 日，采用 MIT 许可证，主要语言是 Python，占代码的 63.6%，仓库里还有 MDX、TypeScript、CSS 等，对应文档站与前端部分。目前 7728 个 Star、662 个 Fork、29 个 Watcher，开放 Issue 44 个。仓库地址是 nonebot/nonebot2，官方文档站在 nonebot.dev，文档源码就在仓库的 website/ 目录里。

主要功能

适配器层隔离平台差异。README 徽章列出 OneBot v11、OneBot v12、QQ Bot、Telegram、飞书、GitHub Bot 几个接入方向，仓库 topics 里还有 cqhttp（CQHTTP）、mirai-bot、qq-guild（QQ 频道）、dingtalk-robot（钉钉机器人）、lark-bot（飞书机器人）等标签。接入哪个平台由适配器决定，插件本身可以不关心消息从哪来。

插件加载与插件商店。插件通过 nonebot.load_plugin 或 nonebot.load_plugins 加载，这一点在仓库 Issue 的示例代码里出现过。社区插件以 nonebot-plugin-* 的形式发布到 PyPI，登记时同时填写 PyPI 项目名和 import 时的包名。插件商店负责收录这些插件，仓库里有两轮清理动作，把没有跟进版本更新的插件从商店移除。

插件配置走环境变量。v2.4.4 允许插件从环境变量中读取配置项，并支持 alias。也就是说同一个配置可以有两个名字，插件改名或换前缀时旧写法还能用。

matcher 结果存储。v2.4.1 加入了存储 matcher 发送 prompt 结果的能力，交互流程中用户回填的内容会被保存下来，插件可以据此继续后续处理。

类型与数据校验兼容。v2.4.3 支持 PEP 695 类型别名，v2.4.2 添加了 pydantic validator 兼容函数，v2.5.0 放宽了 pydantic compat model dump 的类型。这几项都是给写插件的人减少类型标注和校验报错上的摩擦。

内置驱动器与 HTTP 客户端更新。v2.4.3 升级到新版 websockets client API，并细化了内置驱动器请求参数，v2.4.2 修了 httpx 相关的问题。

NB-CLI 脚手架。v2.4.4 更新了 NB-CLI 的新版插件加载格式与对应文档，新建项目、加载插件走命令行工具完成。

日志等级调整。v2.4.1 提升了已加载适配器的日志等级，启动后能看到哪些适配器接上了，v2.4.4 又修了一次 log level 相关的问题。

安装与依赖

Python 版本要求 3.10 及以上，README 徽章标的是 python-3.10+，v2.5.0 这条破坏性变更明确移除了 Python 3.9 支持。系统里如果还是 3.9，先升级解释器再谈安装。

PyPI 上的包名是 nonebot2，README 徽章指向 pypi.python.org/pypi/nonebot2。仓库 README 节选里只出现了指向 PyPI 的徽章链接，没有给出安装命令原文，安装步骤以官方文档站 nonebot.dev 为准，这里不替它编一条。

依赖安装之外，还需要一个可用的平台侧接入配置，比如 OneBot 实现端或对应平台的机器人应用凭据。仓库节选没有展开这部分，官方文档里有各自适配器的配置说明。

最短能跑通的用法

仓库 README 节选里没有可直接复制运行的最小示例，这里不虚构一段代码贴上来。能确认的结构是：

• nonebot/ 是框架源码本体
• packages/ 存放配套包
• tests/ 是测试目录
• website/ 是文档站源码
• scripts/ 存放脚本

实际起步路径通常是：先用 NB-CLI 建一个项目骨架，在配置里选定适配器与接入方式，再写自己的插件文件，最后启动进程。每一步的具体命令请查官方文档，仓库节选没有提供。

关键参数

框架级的配置字段名在 README 节选里没有逐条列出。可以确认的是配置来源与插件有关：v2.4.4 之后，插件支持从环境变量读取配置项，并且支持 alias，同一个配置项可以有别名。写插件时把配置声明成环境变量读取的形式，部署到容器或服务器上改环境变量就能生效，不用改代码。

驱动器的请求参数在 v2.4.3 里被细化过，属于框架内部行为，插件侧一般不用直接碰。其余参数项，仓库节选没有说明。

结果在哪里看

运行结果分两处。终端里看日志，v2.4.1 提升过已加载适配器的日志等级，启动阶段就能从日志判断适配器有没有接上；v2.4.4 修过 log level 相关的问题，如果你的版本较老，日志表现得可能和文档描述不一致。业务结果在聊天平台那边，机器人回复的消息直接出现在群里或私聊里。

文档站的源码在 website/ 目录下，仓库里 MDX 占了 21.5%，说明文档内容和代码放在同一个仓库维护，查 API 用法以 nonebot.dev 为准。

实际使用中的坑

插件帮助信息格式不统一。仓库里那条待解决的 RFC 提出统一插件元数据声明，评论 24 条、reactions 35，是目前清单里热度最高的一条未决问题。现象是：大量插件各自实现帮助功能，一条帮助指令可能触发一堆插件同时响应，输出格式还各不相同。截至这份资料，状态是待解决。

插件商店会清理没跟进版本更新的插件。仓库有过两轮移除动作，一轮评论 74 条，另一轮 55 条，都是把尚未适配新版本的插件从商店移除。状态为已解决。对使用者的影响是：你依赖的插件如果长期没维护，可能直接从商店里消失，装之前最好看一眼它的最后更新时间。

命名空间插件的加载写法被重构过。仓库里有一条关于推广基于 PEP 420 的命名空间插件的提案，评论 25 条，已解决。在它之前，用 nonebot.load_plugin 逐个加载插件会写出一长串调用代码，插件一多就很难看。

插件登记要走固定模板。从 Issue 模板看，提交插件要填 PyPI 项目名、import 包名、标签和配置项示例，信息缺一项就得来回补，评论数在二十到四十条之间的登记贴基本都是这个原因。状态为已解决。

和同类放在一起看

下表把这个项目和两个同类项目放在一起，只列事实层面的差异。

后两个项目解决的是部分重叠的问题：都是把消息接过来做点什么，但 examiner 走的是监听系统通知中心的路子，装好之后写个处理脚本就能跑，不用写插件、不用配适配器；KnifeHub 更直接，打开就是现成工具。NoneBot2 在这两件事上都不如它们省事，你需要先有 Python 3.10 环境，再写插件、配适配器，才能收到第一条消息。如果你的目标只是把通知转发一下，或者用个现成工具，选那两个更合适。

适合谁

适合手上有一批重复的群管理、问答、通知类需求，而且这些需求要同时覆盖 QQ、Telegram、飞书、钉钉里两个以上平台的团队。因为适配器把平台差异挡在外面，插件写一次就能复用，后续加平台只改配置。

适合愿意读文档、能写 Python 异步代码的人。仓库文档和代码同仓维护，版本发布记录完整，2020 年至今持续有提交，遇到问题能在 Issue 区找到同类讨论。

不适合想找一个开箱即用、点几下就能上线机器人的人。从装环境到收到第一条消息，中间需要经过选适配器、配接入凭据、写插件几步，仓库 README 节选里没有可以跳过的捷径。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.6 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。