discord.js音乐队列失效：执行$play添加新曲时跳过旧曲直接播放

核心Bug根因 #

出现「新指令直接顶掉正在播放曲目、不进队列」的现象，本质是两个逻辑叠加导致的：

• 判断语音连接的字段已经废弃失效：代码里用来判断“是否已经在语音频道内”的message.guild.voiceConnection是discord.js v11版本的遗留属性，在v12及之后的所有版本里这个属性不存在，取值永远为undefined。JS读取对象不存在的属性不会抛错，所以控制台不会有任何报错提示，但这会导致这个判断的结果永远为真——哪怕已经在语音频道里正在播放第一首歌，每次发送新的$play指令，代码都会判定“当前没有语音连接”，直接执行join逻辑拿到现有连接，立刻调用play()方法生成新的播放流，直接覆盖掉正在运行的旧dispatcher，强制中断旧曲目开播新歌。
• 缺失队列等待分支逻辑：现有代码只处理了“首次进入语音频道”的播放触发逻辑，完全没有考虑「已经在播歌状态下，新加入队列的曲目要等当前曲目播放结束后自动流转」的场景，哪怕修正了连接判断的字段，只要正在播歌，新push进队列的内容也不会被自动等待播放，因为根本没有对应的状态判断逻辑。

修复步骤 #

1. 替换废弃的连接判断逻辑
   不要再使用message.guild.voiceConnection判断连接状态，改用客户端内置的语音连接缓存获取当前服务器的活跃连接：

   // 从客户端缓存中获取当前服务器的语音连接
   const existingConnection = message.client.voice.connections.get(message.guild.id);
   

2. 补全队列状态判断逻辑
   把新曲目push进队列后，先判断当前是否有正在运行的播放流：
   • 如果没有活跃播放流（刚进频道、队列刚清空），直接触发播放逻辑
   • 如果已经有活跃播放流，只提示用户歌曲已入队，不触发新的play调用，等当前曲目自然结束后，通过dispatcher的end事件自动拉起下一首
3. 调整状态存储结构
   在初始化服务器对应的配置对象时，把连接对象、dispatcher对象都存到servers[guildId]的属性里，避免临时取值导致的状态不同步
4. 解决事件重复绑定问题
   每次生成新的dispatcher时，先清除旧的end事件监听器，避免多次触发play调用时重复绑定回调，导致队列值被多次shift、播放错乱

核心修复代码参考 #

// play指令分支核心逻辑
if(!servers[message.guild.id]) {
  servers[message.guild.id] = {
    queue: [],
    connection: null,
    dispatcher: null
  }
}
const server = servers[message.guild.id];
server.queue.push(args[1]);

const existingConnection = message.client.voice.connections.get(message.guild.id);
if(!existingConnection) {
  // 首次进入语音频道，触发首次播放
  message.member.voice.channel.join().then(connection => {
    server.connection = connection;
    play(connection, message);
  })
} else {
  server.connection = existingConnection;
  // 判断当前是否有正在播放的流
  if(!server.dispatcher || server.dispatcher.destroyed) {
    play(server.connection, message);
  } else {
    message.channel.send(`已将歌曲加入队列，当前队列待播曲目共${server.queue.length}首`);
  }
}

function play(connection, message){
  const server = servers[message.guild.id];
  server.dispatcher = connection.play(ytdl(server.queue[0], {filter: "audioonly"}));
  server.queue.shift();

  server.dispatcher.on("end", () => {
    if(server.queue[0]){
      play(connection, message);
    } else {
      connection.disconnect();
      // 播放完成后清空当前服务器的状态缓存
      delete servers[message.guild.id];
    }
  });
}

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