ProjectHentai/nonebot2
6
0
Fork 0
mirror of https://github.com/nonebot/nonebot2.git synced 2026-01-15 16:22:17 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

✨ Feature: 允许插件从环境变量中读取配置项并支持 alias (#3673)

Browse Source 
Co-authored-by: Ju4tCode <42488585+yanyongyu@users.noreply.github.com>
This commit is contained in:
Azide
2025-10-18 19:43:01 +08:00
committed by GitHub
parent ae3cf2a72f
commit efa3ac3f4c
6 changed files with 114 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
website/docs/appendices/config.mdx
View File

@@ -84,7 +84,7 @@ export CUSTOM_CONFIG='config in environment variables'
那最终 NoneBot 所读取的内容为环境变量中的内容，即 `config in environment variables`。
:::caution 注意
NoneBot 不会自发读取未被定义的配置项的环境变量，如果需要读取某一环境变量需要在 dotenv 配置文件中进行声明。
如果一个环境变量既不是 NoneBot 的[**内置配置项**](#内置配置项)，也不是任何插件所定义的[**插件配置**](#插件配置)，那么 NoneBot 不会自发读取该环境变量，需要在 dotenv 配置文件中先行声明。
:::
### dotenv 配置文件
@@ -242,11 +242,17 @@ weather = on_command(
这种方式可以简洁、高效地读取配置项，同时也可以设置默认值或者在运行时对配置项进行合法性检查，防止由于配置项导致的插件出错等情况出现。
:::tip 提示
:::tip 可配置的事件响应优先级
发布插件应该为自身的事件响应器提供可配置的优先级，以便插件使用者可以自定义多个插件间的响应顺序。
:::
由于插件配置项是从全局配置中读取的，通常我们需要在配置项名称前面添加前缀名，以防止配置项冲突。例如在上方的示例中，我们就添加了配置项前缀 `weather_`。但是这样会导致在使用配置项时过长的变量名，因此我们可以使用 `pydantic` 的 `alias` 或者通过配置 scope 来简化配置项名称。这里我们以 scope 配置为例：
:::tip 插件配置获取逻辑
无论是否在 dotenv 文件中声明了插件配置项，使用 `get_plugin_config` 获取插件配置模型中定义的配置项时都遵循[**配置项的加载**](#配置项的加载)一节中的优先级顺序进行读取。
:::
### 避免插件配置名称冲突
由于插件配置项是从全局配置和环境变量中读取的，通常我们需要在配置项名称前面添加前缀名，以防止配置项冲突。例如在上方的示例中，我们就添加了配置项前缀 `weather_`。但是这样会导致使用配置项时变量名过长，此时我们可以使用 `pydantic` 的 `alias` 或者通过配置 scope 来简化配置项名称。这里我们以 scope 配置为例：
```python title=weather/config.py
from pydantic import BaseModel