NoneBot2 插件开发指南：如何规范发布你的插件

NoneBot2 插件开发指南：如何规范发布你的插件

nonebot2 跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python 项目地址: https://gitcode.com/gh_mirrors/no/nonebot2

前言

作为一款优秀的 Python 异步机器人框架，NoneBot2 提供了强大的插件机制，让开发者可以轻松扩展机器人功能。本文将详细介绍如何规范地将自己开发的插件发布到 NoneBot 商店，供其他用户使用。

插件发布前的准备工作

命名规范的重要性

良好的命名规范有助于用户快速识别插件用途，也便于维护管理。NoneBot 社区推荐以下命名方式：

1. 项目名称：建议采用 nonebot-plugin-{your-plugin-name} 格式，使用短横线连接单词

   • 示例：nonebot-plugin-weather
   • 用于代码仓库、PyPI 包发布等场景

2. 模块名称：建议采用 nonebot_plugin_{your_plugin_name} 格式，使用下划线连接单词

   • 示例：nonebot_plugin_weather
   • 作为 Python 导入时的模块名
   • 应与项目主目录名称一致

合理的项目结构

虽然 NoneBot2 对插件结构没有严格要求，但良好的组织结构能提高可维护性。推荐的基础结构如下：

项目根目录/
├── 插件主目录/       # 应与模块名一致
│   ├── __init__.py  # 插件入口文件
│   └── config.py    # 配置文件（可选）
├── pyproject.toml   # 项目构建配置
└── README.md        # 项目说明文档

对于初学者，可以参考社区提供的项目模板快速搭建结构，但需要注意模板的适用性和时效性。

插件元数据配置

元数据是插件发布的关键部分，它帮助用户了解插件功能和使用方式。必须在插件的 __init__.py 文件中定义 __plugin_meta__ 变量：

from nonebot.plugin import PluginMetadata

__plugin_meta__ = PluginMetadata(
    name="天气查询",  # 插件名称
    description="提供天气查询功能",  # 功能描述
    usage="发送'天气 城市名'查询",  # 使用说明
    
    type="application",  # 插件类型：application或library
    homepage="https://example.com",  # 项目主页
    
    config=Config,  # 配置类（可选）
    supported_adapters={"~onebot.v11"}  # 支持的适配器
)

注意事项：

1. 元数据必须定义在插件最外层（通常是 __init__.py）
2. type 字段必须填写，有效值为 application（面向用户）或 library（为其他插件提供功能）
3. homepage 字段必须提供有效的项目主页
4. 适配器支持列表使用 ~ 作为 nonebot.adapters. 的简写

依赖管理策略

正确的依赖声明能避免运行时问题：

1. 必须添加 nonebot2 为依赖
2. 必须声明使用的适配器依赖，如 nonebot-adapter-onebot
3. 禁止添加 nonebot 为依赖（这是 NoneBot1 的包）
4. 尽量使用宽松的版本约束（避免 == 严格限制）

项目文档编写

良好的文档能帮助用户快速上手。建议在 README.md 中包含：

1. 插件功能介绍
2. 安装方法（至少包含 nb-cli 方式）
3. 配置说明（如有）
4. 使用示例
5. 触发规则（如有）

发布到 PyPI

发布前请确保已完成：

1. 测试插件功能
2. 完善项目文档
3. 正确配置构建系统

根据使用的构建工具，发布命令有所不同：

Poetry 用户

poetry publish --build

PDM 用户

pdm publish

Setuptools 用户

python -m build
twine upload dist/*

发布后建议立即测试安装，确保包内容完整无误。

商店审核流程

1. 在 NoneBot 商店页面提交插件信息

   • 填写准确的 PyPI 包名
   • 提供必要的配置示例（不含敏感信息）

2. 自动检查流程

   • NoneFlow Bot 会验证插件元数据和可加载性
   • 维护者会进行代码审查

3. 审核通过后

   • 插件将出现在商店中
   • 开发者成为 NoneBot 贡献者

如果审核未通过，根据反馈修改后重新提交即可，无需关闭原有流程。

结语

规范化的插件发布流程不仅能让你的作品被更多人使用，也能促进 NoneBot 生态的健康发展。遵循本文指南，你将能够顺利地将精心开发的插件分享给社区。如果在发布过程中遇到问题，可以查阅相关文档或向社区寻求帮助。

nonebot2 跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python 项目地址: https://gitcode.com/gh_mirrors/no/nonebot2