Version: 2.0.1

选择驱动器

驱动器 (Driver) 是机器人运行的基石，它是机器人初始化的第一步，主要负责数据收发。

提示

驱动器的选择通常与机器人所使用的协议适配器相关，如果不知道该选择哪个驱动器，可以先阅读相关协议适配器文档说明。

提示

如何安装驱动器请参考安装驱动器。

驱动器类型

驱动器的类型有两种：

  • ForwardDriver：即客户端型驱动器，多用于使用 HTTP 轮询，连接 WebSocket 服务器等情形。
  • ReverseDriver：即服务端型驱动器，多用于使用 WebHook，接收 WebSocket 客户端连接等情形。

客户端型驱动器具有以下两种功能：

  1. 异步发送 HTTP 请求，自定义 HTTP Method、URL、Header、Body、Cookie、Proxy、Timeout 等。
  2. 异步建立 WebSocket 连接上下文，自定义 WebSocket URL、Header、Cookie、Proxy、Timeout 等。

服务端型驱动器通常为 ASGI 应用框架，具有以下功能：

  1. 协议适配器自定义 HTTP 上报地址以及对上报数据处理的回调函数。
  2. 协议适配器自定义 WebSocket 连接请求地址以及对 WebSocket 请求处理的回调函数。
  3. 用户可以向 ASGI 应用添加任何服务端相关功能，如：添加自定义路由。

配置驱动器

驱动器的配置方法已经在配置章节中简单进行了介绍，这里将详细介绍驱动器配置的格式。

NoneBot 中的客户端和服务端型驱动器可以相互配合使用，但服务端型驱动器仅能选择一个。所有驱动器模块都会包含一个 Driver 子类，即驱动器类，他可以作为驱动器单独运行。同时，客户端驱动器模块中还会提供一个 Mixin 子类，用于在与其他驱动器配合使用时加载。因此，驱动器配置格式采用特殊语法：<module>[:<Driver>][+<module>[:<Mixin>]]*。

其中，<module> 代表驱动器模块路径；<Driver> 代表驱动器类名，默认为 Driver；<Mixin> 代表驱动器混入类名，默认为 Mixin。即，我们需要选择一个主要驱动器，然后在其基础上配合使用其他驱动器的功能。主要驱动器可以为客户端或服务端类型，但混入类驱动器只能为客户端类型。

特别的，为了简化内置驱动器模块路径，我们可以使用 ~ 符号作为内置驱动器模块路径的前缀，如 ~fastapi 代表使用内置驱动器 fastapi。NoneBot 内置了多个驱动器适配，但需要安装额外依赖才能使用，具体请参考安装驱动器。常见的驱动器配置如下：

DRIVER=~fastapi
DRIVER=~aiohttp
DRIVER=~httpx+~websockets
DRIVER=~fastapi+~httpx+~websockets

获取驱动器

在 NoneBot 框架初始化完成后，我们就可以通过 get_driver() 方法获取全局驱动器实例：

from nonebot import get_driver


driver = get_driver()

内置驱动器

None

类型：服务端驱动器

NoneBot 内置的空驱动器，不提供任何收发数据功能，可以在不需要外部网络连接时使用。

DRIVER=~none

FastAPI（默认）

类型：服务端驱动器

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.

FastAPI 是一个易上手、高性能的异步 Web 框架，具有极佳的编写体验。 FastAPI 可以通过类型注解、依赖注入等方式实现输入参数校验、自动生成 API 文档等功能，也可以挂载其他 ASGI、WSGI 应用。

DRIVER=~fastapi

FastAPI 配置项

fastapi_openapi_url

类型：str | None
默认值：None
说明：FastAPI 提供的 OpenAPI JSON 定义地址，如果为 None，则不提供 OpenAPI JSON 定义。

fastapi_docs_url

类型：str | None
默认值：None
说明：FastAPI 提供的 Swagger 文档地址，如果为 None，则不提供 Swagger 文档。

fastapi_redoc_url

类型：str | None
默认值：None
说明：FastAPI 提供的 ReDoc 文档地址，如果为 None，则不提供 ReDoc 文档。

fastapi_include_adapter_schema

类型：bool
默认值：True
说明：FastAPI 提供的 OpenAPI JSON 定义中是否包含适配器路由的 Schema。

fastapi_reload
警告

不推荐开启该配置项，在 Windows 平台上开启该功能有可能会造成预料之外的影响！替代方案：使用 nb-cli 命令行工具以及参数 --reload 启动 NoneBot。

nb run --reload

开启该功能后，在 uvicorn 运行时（FastAPI 提供的 ASGI 底层，即 reload 功能的实际来源），asyncio 使用的事件循环会被 uvicorn 从默认的 ProactorEventLoop 强制切换到 SelectorEventLoop。

相关信息参考 uvicorn#529，uvicorn#1070，uvicorn#1257

后者（SelectorEventLoop）在 Windows 平台的可使用性不如前者（ProactorEventLoop），包括但不限于

  1. 不支持创建子进程
  2. 最多只支持 512 个套接字
  3. ...

具体信息参考 Python 文档

所以，一些使用了 asyncio 的库因此可能无法正常工作，如：

  1. playwright

如果在开启该功能后，原本正常运行的代码报错，且打印的异常堆栈信息和 asyncio 有关（异常一般为 NotImplementedError）， 你可能就需要考虑相关库对事件循环的支持，以及是否启用该功能。

类型：bool
默认值：False
说明：是否开启 uvicorn 的 reload 功能，需要在机器人入口文件提供 ASGI 应用路径。

bot.py
app = nonebot.get_asgi()
nonebot.run(app="bot:app")
fastapi_reload_dirs

类型：List[str] | None
默认值：None
说明：重载监控文件夹列表，默认为 uvicorn 默认值

fastapi_reload_delay

类型：float | None
默认值：None
说明：重载延迟，默认为 uvicorn 默认值

fastapi_reload_includes

类型：List[str] | None
默认值：None
说明：要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值

fastapi_reload_excludes

类型：List[str] | None
默认值：None
说明：不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值

fastapi_extra

类型：Dist[str, Any]
默认值：{}
说明：传递给 FastAPI 的其他参数

Quart

类型：ReverseDriver

Quart is an asyncio reimplementation of the popular Flask microframework API.

Quart 是一个类 Flask 的异步版本，拥有与 Flask 非常相似的接口和使用方法。

DRIVER=~quart

Quart 配置项

quart_reload
警告

不推荐开启该配置项，在 Windows 平台上开启该功能有可能会造成预料之外的影响！替代方案：使用 nb-cli 命令行工具以及参数 --reload 启动 NoneBot。

nb run --reload

类型：bool
默认值：False
说明：是否开启 uvicorn 的 reload 功能，需要在机器人入口文件提供 ASGI 应用路径。

bot.py
app = nonebot.get_asgi()
nonebot.run(app="bot:app")
quart_reload_dirs

类型：List[str] | None
默认值：None
说明：重载监控文件夹列表，默认为 uvicorn 默认值

quart_reload_delay

类型：float | None
默认值：None
说明：重载延迟，默认为 uvicorn 默认值

quart_reload_includes

类型：List[str] | None
默认值：None
说明：要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值

quart_reload_excludes

类型：List[str] | None
默认值：None
说明：不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值

quart_extra

类型：Dist[str, Any]
默认值：{}
说明：传递给 Quart 的其他参数

HTTPX

类型：ForwardDriver

注意

本驱动器仅支持 HTTP 请求，不支持 WebSocket 连接请求。

HTTPX is a fully featured HTTP client for Python 3, which provides sync and async APIs, and support for both HTTP/1.1 and HTTP/2.

DRIVER=~httpx

websockets

类型：ForwardDriver

注意

本驱动器仅支持 WebSocket 连接请求，不支持 HTTP 请求。

websockets is a library for building WebSocket servers and clients in Python with a focus on correctness, simplicity, robustness, and performance.

DRIVER=~websockets

AIOHTTP

类型：ForwardDriver

AIOHTTP: Asynchronous HTTP Client/Server for asyncio and Python.

DRIVER=~aiohttp