NoneBot2插件发布指南：从开发到商店上架全流程

前言

NoneBot2作为一款优秀的Python异步机器人框架，其插件生态是其强大功能的核心支撑。本文将详细介绍如何将开发完成的NoneBot2插件规范地发布到官方插件商店，让更多用户能够方便地使用你的作品。

插件发布前的准备工作

命名规范的重要性

良好的命名规范是插件生态健康发展的基础。NoneBot2社区建议采用以下命名方式：

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

   • 示例：nonebot-plugin-weather
   • 这种命名方式便于在PyPI等平台识别为NoneBot2插件

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

   • 示例：nonebot_plugin_weather
   • 这是Python导入时实际使用的名称

项目结构推荐

合理的项目结构能提高插件的可维护性和易用性。以下是推荐的基础结构：

nonebot-plugin-weather/
├── nonebot_plugin_weather/
│   ├── __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://your-plugin-homepage",  # 项目主页
    
    config=Config,  # 配置类（可选）
    supported_adapters={"~onebot.v11"},  # 支持的适配器
)

元数据注意事项

1. 必须包含type字段，说明插件类型：

   • application：面向终端用户的功能插件
   • library：为其他插件提供支持的库插件

2. homepage字段必须填写有效的项目主页URL

3. supported_adapters应准确列出兼容的适配器，使用~作为nonebot.adapters.的简写

依赖管理最佳实践

合理的依赖管理能避免插件冲突和兼容性问题：

1. 必须添加的依赖：

   • nonebot2：避免"幽灵依赖"问题
   • 使用的适配器：如nonebot-adapter-onebot

2. 避免的实践：

   • 不要添加nonebot依赖（这是NoneBot1的包）
   • 避免使用==严格锁定版本

3. 版本范围建议：

   • 使用>=指定最低版本
   • 使用<限制最高版本（如有必要）

项目文档编写指南

完善的文档能帮助用户快速上手你的插件。README.md应包含：

1. 功能概述：简明扼要地描述插件功能
2. 安装方法：

   nb plugin install nonebot-plugin-weather
   

3. 配置说明：列出所有可配置项及其作用
4. 使用示例：展示典型使用场景
5. 注意事项：使用限制或特殊要求

发布到PyPI流程

构建配置

根据使用的构建工具，在pyproject.toml中配置项目信息：

[project]
name = "nonebot-plugin-weather"
version = "0.1.0"
description = "NoneBot2天气查询插件"
authors = [{name = "YourName", email = "[e-mail]"}]

发布命令示例

根据构建工具不同，发布命令有所差异：

1. 使用Poetry：

poetry publish --build

2. 使用PDM：

pdm publish

3. 使用Setuptools：

python -m build
twine upload dist/*

发布前检查清单

1. 确保所有测试通过
2. 验证插件能正常导入
3. 检查依赖项是否完整
4. 确认文档内容准确

商店审核流程

提交申请

1. 在官方商店页面点击"发布插件"
2. 填写插件信息表单
   • PyPI包名
   • 兼容的NoneBot2版本
   • 必要的配置项（不含敏感信息）

审核阶段

1. 自动化检查：

   • 元数据完整性验证
   • 插件可导入性测试

2. 人工审核：

   • 代码质量检查
   • 功能安全性评估

3. 处理反馈：

   • 根据审核意见修改问题
   • 更新版本后重新触发检查

审核通过后

插件将自动出现在官方商店中，用户可以通过以下方式安装：

nb plugin install nonebot-plugin-weather

后续维护建议

1. 版本更新：

   • 遵循语义化版本规范
   • 及时修复安全问题

2. 用户支持：

   • 维护问题反馈渠道
   • 及时响应issues

3. 文档更新：

   • 保持文档与功能同步
   • 添加变更日志

通过遵循这些规范和实践，你的NoneBot2插件将能够更好地服务于社区用户，同时也能获得更广泛的认可和使用。