Discord.js通过ID或提及获取用户时ID查询偶发失败问题

核心原因 #

偶发查询失败的本质是message.guild.members.cache仅存储机器人本地已缓存的服务器成员数据，未被缓存的成员调用get()方法会直接返回空值，触发用户不存在报错。

排查步骤 #

• 首先确认机器人是否开启了服务器成员权限（Server Members Intent）：Discord.js v12及以上版本都要求在Discord开发者后台手动开启该权限，才能获取全量服务器成员数据。未开启的状态下，机器人默认只能缓存发过消息、被@、刚上线的少量成员，自然大部分用户ID无法查询到。
• 新增调试代码打印args[0]的实际值，确认传入的ID是否为纯数字字符串，有没有携带多余符号、空格，或是参数解析错误把其他内容当成ID传入。
• 打印message.guild.members.cache.size的数值，对比缓存成员数量和服务器实际成员数量的差距，如果差值极大，即可确定是缓存未同步导致的问题。

修复方案 #

方案1：优先走API拉取成员，不依赖本地缓存（推荐） #

将获取用户的逻辑改为异步API拉取，注意要把命令处理函数改为async：

// 先给命令监听函数加async标识，示例：client.on('message', async message => { ... })
let user = message.mentions.members.first();
if (!user && args[0]) {
  try {
    // fetch方法会直接从Discord API拉取成员，不受本地缓存限制
    user = await message.guild.members.fetch(args[0]);
  } catch (err) {
    // 拉取失败才判定为用户不存在
    return message.inlineReply(new Discord.MessageEmbed().setColor("D9B3FF").setTitle("Error").setDescription("User not found."));
  }
}

// 原有逻辑保持不变
if (!user) return message.channel.send(`<@${message.author.id}>: ${insultList[Math.floor(Math.random() * insultList.length)]}`);
message.channel.send(`${user}: ${insultList[Math.floor(Math.random() * insultList.length)]}`);

方案2：启动时全量同步成员缓存（仅适合小型服务器） #

如果机器人仅在少量小服务器运行，可在启动时拉取全量成员同步到缓存，必须开启Server Members Intent才能使用：

client.on('ready', async () => {
  // 遍历所有机器人加入的服务器，拉取全量成员缓存
  for (const guild of client.guilds.cache.values()) {
    await guild.members.fetch();
  }
  console.log('全量成员缓存同步完成')
})

注意：该方案不适合加入了大量大服务器的机器人，会触发Discord API限流。

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