Version: Next

发布插件

NoneBot 为开发者提供了分享插件给大家使用的方式——商店。本章节将会介绍如何将我们写好的插件发布到商店。

提示

本章节仅包含插件发布流程指导，插件开发请查阅前述章节。

准备工作

插件命名规范

NoneBot 插件使用下述命名规范：

  • 对于项目名，建议统一以 nonebot-plugin- 开头，之后为拟定的插件名字，词间用横杠 - 分隔；
    • 项目名用于代码仓库名称、PyPI 包的发布名称等；
    • 本文使用 nonebot-plugin-{your-plugin-name} 为例。
  • 对于模块名，建议与项目名一致，但词间用下划线 _ 分隔，即统一以 nonebot_plugin_ 开头，之后为拟定的插件名字；
    • 模块名用于程序导入使用，应为插件文件（夹）的名称；
    • 本文使用 nonebot_plugin_{your_plugin_name} 为例。

项目结构

提示

本段所述的项目结构仅作推荐，不做强制要求，保证实际可用性即可。

插件程序本身结构可参考插件结构一节，唯一区别在于，插件包可以直接处于项目顶层。

插件项目的一种组织结构如下：

📦 nonebot-plugin-{your-plugin-name}
├── 📂 nonebot_plugin_{your_plugin_name}
│   ├── 📜 __init__.py
│   └── 📜 config.py
├── 📜 pyproject.toml
└── 📜 README.md

第三方项目模板

一些社区用户可能会分享自己制作的项目模板方便大家使用，如：A-kirami/nonebot-plugin-template 等。

提示

本文档不保证第三方模板的适用性。

根据项目模板提供的使用指导补全/修改相应内容后上传到 GitHub 即可。

插件依赖

本段指导填写插件依赖，避免不正确的依赖信息导致插件无法正常工作。

依赖填写的基本原则：程序直接导入了什么第三方库，就添加什么第三方包依赖；能用哪些第三方库的特性，就根据使用的特性锁定第三方包版本。

注意
  1. 插件需要添加 nonebot2 为依赖以避免“幽灵依赖”；
  2. 插件需要将使用的适配器加入依赖列表，如：使用 OneBot 适配器的插件应添加 nonebot-adapter-onebot 依赖；
  3. 由于 nonebot 是指 nonebot1 而非 nonebot2，因此要注意不要将 nonebot 添加为插件的依赖，以免造成冲突；
  4. 尽可能避免使用 == 锁定单一版本，增强与其它插件的兼容性。

填写插件元数据

请注意，插件发布要求必须填写元数据才能通过审核。

下面是一个示例：

nonebot_plugin_{your_plugin_name}/__init__.py
from nonebot.plugin import PluginMetadata


from .config import Config


__plugin_meta__ = PluginMetadata(
    name="{插件名称}",
    description="{插件介绍}",
    usage="{插件用法}",


    type="{插件分类}",
    # 发布必填，当前有效类型有：`library`（为其他插件编写提供功能），`application`（向机器人用户提供功能）。


    homepage="{项目主页}",
    # 发布必填。


    config=Config,
    # 插件配置项类，如无需配置可不填写。


    supported_adapters={"~onebot.v11", "~telegram"},
    # 支持的适配器集合，其中 `~` 在此处代表前缀 `nonebot.adapters.`，其余适配器亦按此格式填写。
    # 若插件可以保证兼容所有适配器（即仅使用基本适配器功能）可不填写，否则应该列出插件支持的适配器。
)
注意

__plugin_meta__ 变量必须处于插件最外层（如 __init__.py 中），否则无法正常识别。

一般做法是在 __init__.py 中定义 __plugin_meta__。

提示

带花括号 {} 的内容需要自行替换，注意一定要把原有的花括号去掉。

准备项目主页

通常可以使用 GitHub 项目页面作为项目主页，在 README.md 文件中编写插件介绍等内容。

内容大致包括：

  • 插件功能介绍
  • 安装方法（建议至少有 nb-cli 方式安装，不要使用旧式的 bot.py 配置）
  • 插件配置项（若无可跳过）
  • 插件设置的触发规则（若无可跳过）
  • 插件的其它用法（按需编写）
提示

可以参考第三方项目模板。

发布至 PyPI

根据选用的构建系统，在项目的 pyproject.toml 中填入必要信息后进行构建与发布。

提示

不同构建工具的使用可能存在差别。本文仅以 pdm, poetry, setuptools 构建系统本地构建与发布为示例讲解，其余构建/管理工具等和自动化构建的用法请读者自行探索。

poetry publish --build  # 构建并发布


# 等效于以下两个命令
poetry build            # 只构建
poetry publish          # 只发布先前的构建
提示

发布前建议自行测试构建包是否可用，避免遗漏代码文件或资源文件等问题。

商店审核

提交申请

完成在 PyPI 的插件发布流程后，前往商店页面，切换到插件页签，点击 发布插件 按钮。

在弹出的插件信息提交表单内，填入您所要发布的相应插件信息。请注意，如果插件需要必要配置项才能正常导入，请在“插件配置项”中填写必要的内容（请勿填写密钥等敏感信息）。

完成填写后，点击 发布 按钮，这将自动跳转 NoneBot 仓库内的“发布插件”页面。确认信息无误后点击页面下方的 Submit new issue 按钮进行最终提交即可。

等待插件审核

插件发布 Issue 创建后，将会经过 NoneFlow Bot 的自动前置检查，以确保插件信息正确无误、插件能被正确加载。

提示

若插件检查未通过或信息有误，不必关闭当前 Issue。只需更新插件并上传到 PyPI/修改信息后在当前 Issue 追加任意内容的评论（如“已更新”等）即可重新触发插件检查。

之后，NoneBot 的维护者和一些插件开发者会初步检查插件代码，帮助减少该插件的问题。

完成这些步骤后，您的插件将会被自动合并到商店，而您也将成为 NoneBot 贡献者的一员。