如何使用discord.py在Python中开发模块化的Discord bot

首先明确：功能拆分到独立Python文件的需求完全可以实现，不需要把所有代码都写在同一个文件里。你当前方案无法运行的核心问题是直接跨文件导入bot实例的做法容易触发循环导入，或是命令注册逻辑晚于bot启动逻辑，导致命令没有被正确注册。

discord.py官方提供了Cog（扩展）机制用于多文件功能拆分，正确实现流程如下： #

步骤1：编写独立功能的子模块文件 #

以 moderation 管理功能为例，新建mod_moderation.py文件，代码结构如下：

from discord.ext import commands

# 定义功能对应的Cog类
class ModerationCog(commands.Cog):
    def __init__(self, bot):
        # 接收主文件传入的bot实例，无需主动导入main.py的对象
        self.bot = bot
    
    # 功能命令使用@commands.command装饰器注册
    @commands.command(name="kick")
    async def kick_member(self, ctx, member: commands.MemberConverter):
        await member.kick()
        await ctx.send(f"已踢出成员 {member.mention}")

# 必须定义setup函数，主文件加载扩展时会自动调用
async def setup(bot):
    await bot.add_cog(ModerationCog(bot))

步骤2：主文件加载子扩展 #

在main.py中初始化bot后，主动加载所有子模块即可，无需手动导入子模块的命令，也不需要提前把bot实例导出给子模块：

import asyncio
from discord.ext import commands

# 按你的需求配置bot初始化参数，intents必须按启用的权限填写
bot = commands.Bot(command_prefix="!", intents=...)

async def load_all_extensions():
    # 按模块名加载所有功能子文件，不需要加.py后缀
    await bot.load_extension("mod_moderation")
    # 有多个功能文件时依次添加即可
    # await bot.load_extension("mod_fun")
    # await bot.load_extension("mod_settings")

async def main():
    async with bot:
        # 先加载所有扩展，再启动bot
        await load_all_extensions()
        await bot.start("你的Bot令牌")

asyncio.run(main())

常见问题说明 #

• 如果你没有自定义on_message事件，不需要手动调用bot.process_commands，discord.py会自动处理命令触发逻辑。如果你重写了on_message事件，必须在事件逻辑的末尾添加await bot.process_commands(message)，否则所有命令都会失效。
• 功能代码修改后不需要重启整个Bot，可以调用await bot.reload_extension("模块名")实现热重载。

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