Discord.py混合命令报错‘unsupported type annotation’求助

问题根源分析 #

你遇到的unsupported type annotation报错和命令执行异常，主要是这几个问题导致的：

• 非Cog类中的hybrid命令不需要self参数，多余的self会打乱discord.py的参数解析逻辑，引发类型注解错误
• 参数类型注解写法错误：amount=int是Python旧版语法，discord.py需要标准的amount: int类型注解
• 存在未加await的ctx.send调用，会导致协程未执行，命令无响应
• 错误提示中的数字逻辑不一致（判断>20却提示不能超过50）

修正后的代码 #

@bot.hybrid_command(name="clear")
@commands.has_permissions(manage_messages=True)
async def clear(ctx: commands.Context, amount: int):
    if amount > 50:
        await ctx.send("由于Discord的速率限制，我一次最多只能删除50条消息。")
    elif amount <= 0:
        await ctx.send("我不能删除0条消息")
        return

    await ctx.channel.purge(limit=amount + 1)
    await ctx.send(f"成功删除{amount}条消息！")

关键修改点说明 #

• 移除了self参数：如果你的命令不是写在Cog类里，直接用@bot.hybrid_command装饰的函数不需要self，加了会让discord.py把它当成第一个位置参数解析，导致上下文类型注解识别失败
• 把amount=int改成amount: int：这是Python 3.5+标准的类型注解语法，discord.py依赖这个来正确解析命令参数
• 给所有ctx.send加上await：send是异步方法，必须用await才能执行，否则只会返回一个未执行的协程对象，导致命令看起来没反应
• 统一了数字逻辑：把判断条件改成amount>50，和提示文案保持一致，避免逻辑混乱

额外注意事项 #

如果你的机器人是基于discord.py v2.x版本，确保已经同步了命令到Discord服务器：

# 在机器人启动时添加同步命令的代码
async def setup_hook():
    await bot.tree.sync()

bot.setup_hook = setup_hook

这一步是hybrid命令能正常在交互中使用的必要操作。

内容的提问来源于stack exchange，提问作者atomfrog