nonebot-plugin-custom-welcome 0.2.1

NoneBot2 自定义加群欢迎插件

NoneBot2 自定义加群欢迎插件

一个基于 NoneBot2 + OneBot V11 的自定义加群欢迎插件，支持设置欢迎文案、欢迎图片，并支持权限管理。

功能特性

• 新人入群自动欢迎（@新人 + 文案 + 图片）
• 支持自定义欢迎文案（多行文本）
• 支持自定义欢迎图片（从消息或引用消息提取）
• 支持查看当前欢迎配置
• 支持清除欢迎配置
• 权限控制：仅群主、群管理员、SUPERUSER 可设置
• 防重复机制：同群 30 秒内只触发一次欢迎
• 本地 JSON 存储，无需 Redis

安装方法

方法一：从本地安装（推荐开发测试）

git clone https://github.com/TonyLiangP2010405/nonebot-plugin-custom-welcome.git
cd nonebot-plugin-custom-welcome
pip install -e .

方法二：直接复制到项目

将 nonebot_plugin_custom_welcome 文件夹复制到你的 NoneBot 项目 src/plugins/ 目录下。

使用方法

新人入群

当有新人加入群聊时，机器人会自动发送：

• @新人
• 该群配置的欢迎文案
• 该群配置的欢迎图片（如有）

如果群没有配置欢迎内容，则发送默认欢迎：@新人 欢迎新人~！

设置欢迎文案

#设置欢迎文案 欢迎加入本群，请先看群公告~

或：

#设置欢迎文案
欢迎加入本群
请先看群公告

设置欢迎图片

方式一：直接发送图片并附带命令

#设置欢迎图片 [图片]

方式二：引用图片消息

先发送一张图片，然后引用该图片发送：

#设置欢迎图片

查看欢迎

#查看欢迎

设置群规

#设置群规 本群禁止发广告，违者踢出~

查看群规

#查看群规

清除群规

#清除群规

权限说明

命令	权限要求
设置欢迎文案	群主 / 管理员 / SUPERUSER
设置欢迎图片	群主 / 管理员 / SUPERUSER
查看欢迎	任何人
清除欢迎	群主 / 管理员 / SUPERUSER
设置群规	群主 / 管理员 / SUPERUSER
查看群规	任何人
清除群规	群主 / 管理员 / SUPERUSER

权限不足时回复：只有群主或管理员可以设置欢迎消息哦~

配置项

在 .env 文件中可以添加以下配置：

# 默认欢迎文案（可选，默认：欢迎新人~！）
CUSTOM_WELCOME_DEFAULT_TEXT=欢迎新人~！

# 数据存储目录（可选，默认：data/custom_welcome）
CUSTOM_WELCOME_DATA_DIR=data/custom_welcome

数据存储

插件使用本地 JSON 文件存储配置：

data/custom_welcome/
  welcome.json          # 群配置
  images/
    {group_id}/
      welcome.jpg       # 群欢迎图片

welcome.json 格式：

{
  "123456789": {
    "text": "欢迎加入本群~",
    "image": "data/custom_welcome/images/123456789/welcome.jpg"
  }
}

技术细节

• 适配器：nonebot-adapter-onebot (OneBot V11)
• 图片下载：httpx 异步客户端，不会阻塞事件循环
• 配置写入：临时文件 + rename 的原子操作，避免写坏配置
• 路径处理：pathlib，兼容 Windows 和 Linux
• 本地图片：file:/// URI 格式，兼容 NapCat、Lagrange、go-cqhttp

测试方法

1. 将插件加载到 NoneBot 项目中
2. 启动 NoneBot，确认无报错
3. 在群聊中发送 #查看欢迎，确认回复"该群尚未设置欢迎内容"
4. 发送 #设置欢迎文案 测试欢迎，确认设置成功
5. 发送一张图片后，发送 #设置欢迎图片，确认设置成功
6. 发送 #查看欢迎，确认文案和图片都显示
7. 让一个小号入群，确认收到 @小号 测试欢迎 和图片
8. 发送 #清除欢迎，确认清除成功
9. 再次让小号入群，确认收到默认欢迎
10. 普通群员发送设置/清除命令，确认被权限拒绝

自检清单

• 插件能被 NoneBot 正常 import
• 无语法错误
• 无缺失依赖
• 无错误的 NoneBot API 调用
• #设置欢迎文案 xxx 能正确保存
• #设置欢迎图片 能从当前消息或引用消息中提取图片
• 新人入群时能发送 @ + 文案 + 图片
• 没有配置时发送默认欢迎
• 普通群员无法设置和清除
• 清除欢迎后图片文件也被删除
• Windows 路径可用
• 多群配置互不影响