Discord.js v13 Bot批量操作服务器成员角色功能异常问题

原有代码问题根源 #

• 直接遍历message.guild.members.cache仅能处理本地已缓存的成员，未缓存的成员会被完全跳过，这是仅部分账号生效的核心原因
• 未做机器人账号过滤，不符合排除机器人的需求
• 循环内重复发送频道消息会造成严重刷屏
• 未等待角色操作的异步请求返回，也未做异常捕获，容易触发API速率限制或静默失败
• 角色判断逻辑存在冲突：原逻辑会把所有没有成员角色的用户都加上成员角色，包括本来就不持有两个目标角色的访客用户

修复后可直接使用的代码 #

const { Client, Intents } = require('discord.js');
// 初始化客户端时必须开启成员意图，否则无法拉取全量成员
const client = new Client({
  intents: [
    Intents.FLAGS.GUILDS,
    Intents.FLAGS.GUILD_MESSAGES,
    Intents.FLAGS.GUILD_MEMBERS // 必须开启该权限项
  ]
});

// 角色ID常量统一管理
const MEMBER_ROLE_ID = "871442068508123136";
const MAINTENANCE_ROLE_ID = "978322456328687656";

client.on('messageCreate', async(message) => {
  // 跳过所有机器人发送的消息
  if (message.author.bot) return;
  if (!message.content.startsWith(config.prefix)) return;

  let args = message.content.slice(config.prefix.length).trim().split(/ +/);
  let command = args.shift().toLowerCase();

  if (command === 'manutencao') {
    // 前置权限校验
    if (!message.member.permissions.has("MANAGE_ROLES")) {
      return message.channel.send("你没有使用该命令的权限");
    }
    if (!message.guild.me.permissions.has("MANAGE_ROLES")) {
      return message.channel.send("机器人缺少管理角色权限，无法执行操作");
    }

    // 强制拉取服务器全量成员，跳过本地缓存
    const allMembers = await message.guild.members.fetch();
    // 过滤掉所有机器人账号，仅处理普通人类成员
    const validMembers = allMembers.filter(member => !member.user.bot);

    // 自动识别当前维护状态，避免逻辑冲突
    const isMaintenanceOn = validMembers.some(m => m.roles.cache.has(MAINTENANCE_ROLE_ID));
    const statusMsg = isMaintenanceOn ? "正在关闭维护模式..." : "正在开启维护模式...";
    const replyMsg = await message.channel.send(statusMsg);

    // 串行批量处理成员角色，加延迟避免触发API限流
    for (const member of validMembers.values()) {
      try {
        if (isMaintenanceOn) {
          // 关闭维护流程：移除维护角色，加回普通成员角色
          if (member.roles.cache.has(MAINTENANCE_ROLE_ID)) {
            await member.roles.remove(MAINTENANCE_ROLE_ID);
          }
          await member.roles.add(MEMBER_ROLE_ID);
        } else {
          // 开启维护流程：移除普通成员角色，添加维护角色
          if (member.roles.cache.has(MEMBER_ROLE_ID)) {
            await member.roles.remove(MEMBER_ROLE_ID);
          }
          await member.roles.add(MAINTENANCE_ROLE_ID);
        }
        // 单成员操作后加100ms延迟，规避Discord接口速率限制
        await new Promise(resolve => setTimeout(resolve, 100));
      } catch (err) {
        console.log(`处理成员${member.user.tag}角色失败：`, err);
      }
    }

    // 操作完成后仅发送一次全局通知，不会刷屏
    await replyMsg.edit(`维护模式已${isMaintenanceOn ? "关闭" : "开启"}，共处理${validMembers.size}名成员`);
  }
});

必做配置检查 #

• 前往Discord开发者后台，在机器人的Privileged Gateway Intents板块开启Server Members Intent开关，和代码里的GUILD_MEMBERS意图对应，否则拉取不到全量成员列表
• 进入服务器角色设置页，把机器人的角色拖动到「普通成员角色」「维护角色」的上方，Discord接口规则是仅能修改比自身角色层级低的角色，层级不够会直接操作失败
• 给机器人授予管理角色权限，否则无法修改成员的角色分配

内容的提问来源于stack exchange，提问作者Daniel Filipe Teixeira Ferreir