--- sidebar_position: 1 description: 项目配置方式与配置项 options: menu: weight: 21 category: guide --- # 配置 在上一章节中,我们创建了默认的项目结构,其中 `.env` 和 `.env.*` 均为项目的配置文件,下面将介绍几种 NoneBot 配置方式以及配置项。 :::danger 警告 请勿将敏感信息写入配置文件并提交至开源仓库! ::: ## 配置方式 ### .env 文件 NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感),默认值为 `prod`。 这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。 `.env` 文件是基础环境配置文件,该文件中的配置项在不同环境下都会被加载,但会被 `.env.{ENVIRONMENT}` 文件中的配置所覆盖。 NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 进行配置处理,并对 `pydantic` 的行为做出了更改,详见下方说明。 现在,我们在 `.env` 文件中写入当前环境信息: ```bash # .env ENVIRONMENT=dev CUSTOM_CONFIG=common config # 这个配置项在任何环境中都会被加载 ``` 如你所想,之后 NoneBot 就会从 `.env.dev` 文件中加载环境变量。 :::important 参考文档 `.env` 相关文件的加载使用 `dotenv` 语法,请参考 [`dotenv` 文档](https://saurabh-kumar.com/python-dotenv/) ::: :::warning 提示 由于 `pydantic` 使用 JSON 解析配置项,请确保配置项值为 JSON 格式的数据。如: ```bash list=["123456789", "987654321", 1] test={"hello": "world"} ``` 如果配置项值解析失败将作为 **字符串** 处理。 特别的,如果配置项 **为空** ,则会从 **系统环境变量** 中获取值,如果不存在则为空字符串。 ::: ### .env.\* 文件 NoneBot 默认会从 `.env.{ENVIRONMENT}` 文件加载配置,但是可以在 NoneBot 初始化时指定加载某个环境配置文件: `nonebot.init(_env_file=".env.dev")`,这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。 配置语法与 `.env` 文件相同。 示例及说明: ```bash HOST=0.0.0.0 # 配置 NoneBot 监听的 IP/主机名 PORT=8080 # 配置 NoneBot 监听的端口 SUPERUSERS=["123456789", "987654321"] # 配置 NoneBot 超级用户 NICKNAME=["awesome", "bot"] # 配置机器人的昵称 COMMAND_START=["/", ""] # 配置命令起始字符 COMMAND_SEP=["."] # 配置命令分割字符 # Custom Configs CUSTOM_CONFIG1="config in env file" CUSTOM_CONFIG2= # 留空则从系统环境变量读取,如不存在则为空字符串 ``` 详细的配置项可以参考 [配置项](#详细配置项) 。 ### 系统环境变量 如果在系统环境变量中定义了配置,则一样会被读取。 ### bot.py 文件 配置项也可以在 NoneBot 初始化时传入。此处可以传入任意合法 Python 变量。当然也可以在初始化完成后修改或新增。 示例: ```python # bot.py import nonebot nonebot.init(custom_config3="config on init") config = nonebot.get_driver().config config.custom_config3 = "changed after init" config.custom_config4 = "new config after init" ``` ## 配置优先级 `bot.py` 文件( `nonebot.init` ) > 系统环境变量 > `.env`, `.env.*` 文件 ## 读取配置项 配置项可以通过三种类型的对象获取:`driver`, `adapter`, `bot`。 ```python import nonebot # driver nonebot.get_driver().config.custom_config # bot nonebot.get_bot().config.custom_config # adapter nonebot.get_driver()._adapters["adapter_name"].config.custom_config ``` ## 详细配置项 配置项的 API 文档可以前往 [Class Config](../api/config.md#class-config) 查看。 ### Driver - **类型**: `str` - **默认值**: `"~fastapi"` NoneBot 运行所使用的驱动器。主要分为 `ForwardDriver`, `ReverseDriver` 即客户端和服务端两类。 配置格式采用特殊语法:`[:][+[:]]*` 其中 `` 为驱动器模块名,可以使用 `~` 作为 `nonebot.drivers.` 的简写;`` 为驱动器类名,默认为 `Driver`;`` 为驱动器混入的类名,默认为 `Mixin`。 NoneBot 内置了几个常用驱动器,包括了各类常用功能,常见驱动器配置如下: ```env DRIVER=~fastapi DRIVER=~httpx+~websockets DRIVER=~fastapi+~httpx+~websockets DRIVER=~fastapi+~aiohttp ``` 各驱动器的功能与区别请参考 [选择驱动器](./choose-driver.md) 。 ### Host - **类型**: `IPvAnyAddress` - **默认值**: `127.0.0.1` 使用 `ReversedDriver` 时,NoneBot 监听的 IP/主机名。 ```env HOST=127.0.0.1 ``` ### Port - **类型**: `int` - **默认值**: `8080` 使用 `ReversedDriver` 时,NoneBot 监听的端口。 ```env PORT=8080 ``` ### Log Level - **类型**: `int | str` - **默认值**: `INFO` NoneBot 日志输出等级,可以为 `int` 类型等级或等级名称 参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。 ```env LOG_LEVEL=INFO ``` :::tip 提示 日志等级名称应为大写,如 `INFO`。 ::: ### API Timeout - **类型**: `Optional[float]` - **默认值**: `30.0` API 请求超时时间,单位为秒。 ```env API_TIMEOUT=30.0 ``` ### SuperUsers - **类型**: `Set[str]` - **默认值**: `set()` 机器人超级用户,可以使用权限 [`SUPERUSER`](../api/permission.md#SUPERUSER)。 ```env SUPERUSERS=["1234567890"] ``` ### Nickname - **类型**: `Set[str]` - **默认值**: `set()` 机器人昵称,通常协议适配器会根据用户是否 @user 或者是否以机器人昵称开头来判断是否是向机器人发送的消息。 ```env NICKNAME=["bot"] ``` ### Command Start 和 Command Separator - **类型**: `Set[str]` - **默认值**: - Command Start: `{"/"}` - Command Separator: `{"."}` 命令消息的起始符和分隔符。用于 [`command`](../api/rule.md#command) 规则。 ```env COMMAND_START={"/", "!"} COMMAND_SEP={".", "/"} ``` ### Session Expire Timeout - **类型**: `timedelta` - **默认值**: `timedelta(minutes=2)` 用户会话超时时间,配置格式参考 [`Pydantic Field`](https://pydantic-docs.helpmanual.io/usage/types/#datetime-types) 。 ```env SESSION_EXPIRE_TIMEOUT=120 ```