Python开发Discord Bot时外部Cog类命令无法被识别的问题

检查Cog的加载逻辑 #

主类必须显式加载Cog，否则Bot无法识别Cog内的命令。可以在Bot启动时直接加载，或者添加管理员命令动态加载：

• 启动时同步加载：

# 主文件中Bot初始化后添加
async def main():
    async with bot:
        await bot.load_extension('cogs.your_cog_filename')  # 路径为Python模块路径，比如cogs目录下的test_cog.py就写'cogs.test_cog'
        await bot.start('YOUR_BOT_TOKEN')

• 添加管理员加载命令（需Bot拥有者权限）：

@bot.command()
@commands.is_owner()
async def load(ctx, extension):
    await bot.load_extension(extension)
    await ctx.send(f"已加载扩展 {extension}")

规范Cog类的写法 #

Cog类必须遵循Discord.py的规范，否则无法被正确识别：

import discord
from discord.ext import commands

class YourCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    # 用@commands.command()装饰Cog内的命令，而非@bot.command()
    @commands.command()
    async def test(self, ctx):
        await ctx.send("Cog内的test命令生效！")

    @commands.command()
    async def limpiar(self, ctx, amount: int = 5):
        await ctx.channel.purge(limit=amount)
        await ctx.send(f"已删除{amount}条消息", delete_after=3)

# 必须包含setup异步函数，作为Cog的加载入口
async def setup(bot):
    await bot.add_cog(YourCog(bot))

验证命令前缀与Intents权限 #

• 确保触发命令时使用的前缀和Bot初始化时设置的一致，比如Bot初始化用command_prefix='!'，就必须用!test触发命令。
• 开启message_content Intent，否则Bot无法读取命令消息：

intents = discord.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix='!', intents=intents)

排查控制台加载错误 #

如果Cog加载失败，控制台会输出具体错误：

• ExtensionNotFound：检查Cog的模块路径是否正确
• AttributeError：检查Cog类是否继承自commands.Cog，装饰器是否正确使用
• RuntimeError：检查setup函数是否为异步函数，是否正确调用add_cog

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