Discord.py机器人执行join语音频道命令时触发KeyError问题排查

问题现象 #

我正在使用Discord.py开发音乐机器人，join命令存在异常：

• 当用户不在语音频道时，机器人能正确发送提示：You're not in a voice channel!
• 当用户处于语音频道内时，机器人无法加入频道，触发KeyError，错误信息如下：

File "c:\file location\musicCog.py", line 159, in join
    await self.join_VC(ctx, userChannel)
  File "c:\file location\musicCog.py", line 77, in join_VC
    if self.vc[id] == None or not self.vc[id].is_connected:
       ~~~~~~~^^^^
KeyError: (guild id)

问题原因 #

1. 字典键未初始化：现有代码仅在on_ready事件中初始化服务器相关的字典（vc、musicQueue等），但该事件仅在机器人启动时执行一次。如果机器人启动后新加入服务器，或者服务器缓存未在on_ready时完全加载，对应服务器的ID就不会被添加到字典中，直接访问会触发KeyError。
2. 方法调用错误：is_connected是语音客户端的方法，需要加括号调用is_connected()。原代码未加括号，会将方法对象本身当作布尔值（永远为True），导致判断逻辑失效。

解决方案 #

1. 添加新服务器初始化逻辑 #

新增on_guild_join事件监听器，处理机器人新加入服务器时的状态初始化：

@commands.Cog.listener()
async def on_guild_join(self, guild):
    guild_id = int(guild.id)
    # 初始化新服务器的所有状态字典
    self.musicQueue[guild_id] = []
    self.queueIndex[guild_id] = 0
    self.is_playing[guild_id] = self.is_paused[guild_id] = False
    self.vc[guild_id] = discord.utils.get(self.bot.voice_clients, guild=guild) or None

2. 修复join_VC方法 #

在join_VC方法中先检查并补全服务器状态，同时修复is_connected的调用：

async def join_VC(self, ctx, channel):
    guild_id = int(ctx.guild.id)
    
    # 检查当前服务器是否已初始化，未初始化则补全
    if guild_id not in self.vc:
        self.musicQueue[guild_id] = []
        self.queueIndex[guild_id] = 0
        self.is_playing[guild_id] = self.is_paused[guild_id] = False
        self.vc[guild_id] = discord.utils.get(self.bot.voice_clients, guild=ctx.guild) or None
    
    # 修复is_connected的调用，添加括号
    if self.vc[guild_id] is None or not self.vc[guild_id].is_connected():
        self.vc[guild_id] = await channel.connect()
        
        if self.vc[guild_id] is None:
            await ctx.send("Couldn't connect to the voice channel.")
            return
    else: 
        await self.vc[guild_id].move_to(channel)

3. 封装初始化方法（可选） #

为避免重复代码，可封装一个通用的服务器状态初始化方法，在需要的地方调用：

def init_guild_state(self, guild_id):
    if guild_id not in self.musicQueue:
        self.musicQueue[guild_id] = []
        self.queueIndex[guild_id] = 0
        self.is_playing[guild_id] = self.is_paused[guild_id] = False
        self.vc[guild_id] = discord.utils.get(self.bot.voice_clients, id=guild_id) or None

之后在on_ready、on_guild_join、join_VC等方法中，只需调用self.init_guild_state(guild_id)即可完成初始化。

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