discord.py 2.0加载cogs后命令错误无输出修复方案

• 你使用async with client + client.start()的异步启动模式时，discord.py不会自动完成基础日志初始化配置，库内部抛出的绝大多数运行时、命令执行错误都通过标准logging模块输出，没有配置日志handler时这些内容会被直接丢弃。
• 传统client.run()写法内部会自动挂载基础日志handler，所以可以正常看到报错，但你之前把cogs加载逻辑写在client.run()外层的同步上下文里，异步的load_extensions()无法正常执行，才会出现cogs加载失败的问题。
• 没有注册全局on_command_error监听器时，部分命令层面的异常会被库内部静默捕获，不会直接抛出到控制台。

1. 配置基础日志 #

discord.py的所有运行日志、错误信息都通过Python标准logging模块输出，你可以自己配置日志规则，也可以直接调用库内置的日志初始化方法：

# 方式1：调用discord.py内置的日志配置，和client.run()默认使用的配置一致
from discord.utils import setup_logging
setup_logging()

# 方式2：自定义日志格式和级别
# import logging
# logging.basicConfig(
#     level=logging.INFO,
#     format="%(asctime)s | %(levelname)s | %(name)s: %(message)s"
# )

2. 使用2.0版本推荐的setup_hook加载扩展 #

discord.py 2.0新增了setup_hook异步生命周期钩子，会在机器人登录成功、正式开始处理事件前自动执行，无论你用client.start()还是client.run()启动都能正常触发，彻底解决cogs加载不生效的问题：

@client.event
async def setup_hook():
    for filename in os.listdir("./cogs"):
        if filename.endswith(".py"):
            await client.load_extension(f"cogs.{filename[:-3]}")
            print(f"成功加载cog扩展：cogs.{filename[:-3]}")

原来的独立load_extensions函数和main函数里的加载调用可以直接删掉。

3. 添加全局命令错误监听器 #

注册on_command_error事件，统一捕获命令执行时的异常，打印完整错误栈方便调试：

@client.event
async def on_command_error(ctx, error):
    # 忽略命令不存在的错误
    if isinstance(error, commands.CommandNotFound):
        return
    # 打印完整错误栈到控制台
    logging.error(f"命令 {ctx.command.qualified_name} 执行异常", exc_info=error)
    # 给触发命令的用户返回错误提示，可按需自定义
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(f"参数缺失：必填参数 `{error.param.name}` 未传入")
    elif isinstance(error, commands.BotMissingPermissions):
        await ctx.send(f"机器人权限不足，缺少：{', '.join(error.missing_permissions)}")
    else:
        await ctx.send(f"命令执行出错：{str(error)}")

4. 启动逻辑选择 #

配置完上述内容后，两种启动方式都可以正常加载cogs、输出错误日志，按需选择即可：

异步启动方式（原写法适配） #

async def main():
    async with client:
        await client.start("你的机器人token")

asyncio.run(main())

简化同步启动方式 #

不需要写异步main函数，直接调用即可，cogs会通过setup_hook自动加载：

client.run("你的机器人token")

修改完成后，可以写一个会抛出异常的测试命令验证效果：

@client.command()
async def test_err(ctx):
    raise ValueError("测试错误输出")

执行!test_err时，控制台会输出完整的错误栈和日志信息，不需要再手动加print排查问题。

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