Discord.py拆分命令至Cogs文件夹后加载失败求助

1. 核心问题根源 #

discord.py 2.0及以后版本中，load_extension已改为异步方法，必须在异步上下文里通过await调用：同步代码直接调用会触发RuntimeWarning，同步函数里硬加await则会抛出TypeError。

2. 确认项目结构与路径合法性 #

你的项目必须遵循以下结构，否则Python无法识别cogs为合法包：

项目根目录/
├─ main.py
└─ cogs/
   ├─ __init__.py  # 必须是空文件，让Python将cogs识别为包
   └─ ping.py

加载时路径需写成cogs.ping（用点号表示包层级），不能写cogs/ping或直接写ping。

3. 两种正确的加载实现方式 #

方式一：用setup_hook加载（官方推荐） #

将加载逻辑封装到异步函数中，绑定到bot的setup_hook，它会在bot启动前自动执行：

import discord
from discord.ext import commands

# 按需启用intents，必须开启message_content才能接收命令
intents = discord.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix="!", intents=intents)

async def load_all_cogs():
    # 加载单个cog
    await bot.load_extension("cogs.ping")
    # 如需加载多个cog，继续添加：await bot.load_extension("cogs.xxx")

# 将加载函数绑定到setup_hook
bot.setup_hook = load_all_cogs

@bot.event
async def on_ready():
    print(f"已登录：{bot.user}")

bot.run("你的机器人TOKEN")

方式二：用asyncio.run包裹主逻辑 #

将启动和加载逻辑都放到异步主函数中，通过asyncio.run执行：

import discord
import asyncio
from discord.ext import commands

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

async def main():
    await bot.load_extension("cogs.ping")
    await bot.start("你的机器人TOKEN")

if __name__ == "__main__":
    asyncio.run(main())

4. 检查ping.py的Cog格式是否正确 #

discord.py 2.0+的Cog必须包含异步setup函数，示例如下（别用旧版本写法）：

from discord.ext import commands

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

    @commands.command()
    async def ping(self, ctx):
        await ctx.send(f"Pong! {round(self.bot.latency * 1000)}ms")

# 必须有这个异步setup函数，用于注册Cog
async def setup(bot):
    await bot.add_cog(Ping(bot))

5. 常见错误排查 #

• RuntimeWarning：未加await直接调用bot.load_extension，补上await并将代码移到异步函数中即可。
• TypeError：在同步函数中使用了await，把加载逻辑转移到async函数内。
• ExtensionNotFound：检查cogs文件夹是否有__init__.py，加载路径是否为cogs.ping，ping.py是否存在语法错误。

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