最新版Discord.js中如何在ready事件下获取服务器内指定角色的全部成员

必做前置配置 #

• 初始化客户端时必须显式声明GuildMembers意向，这是旧版代码在新版本运行失效的核心原因
• 前往Discord开发者门户的机器人设置页，打开Server Members Intent开关，否则调用成员查询接口会直接触发权限报错

可运行完整代码 #

const { Client, GatewayIntentBits } = require('discord.js');
const client = new Client({
    intents: [
        GatewayIntentBits.Guilds,
        GatewayIntentBits.GuildMembers
    ]
});

client.on('ready', async () => {
    const hostGuild = client.guilds.cache.get('822234110369595443');
    if (!hostGuild) {
        console.log('未定位到目标服务器，请检查服务器ID是否填写正确');
        return;
    }

    // 匹配名称为'xyz'的目标角色
    const targetRole = hostGuild.roles.cache.find(role => role.name === 'xyz');
    if (!targetRole) {
        console.log('未找到名称为xyz的角色');
        return;
    }

    // 从成员缓存中过滤出所有持有该角色的条目
    const roleMemberList = hostGuild.members.cache.filter(member => 
        member.roles.cache.has(targetRole.id)
    );

    // 结果输出示例
    console.log(`持有xyz角色的成员共 ${roleMemberList.size} 位：`);
    roleMemberList.forEach(member => {
        console.log(`- ${member.user.globalName || member.user.username}（用户ID：${member.id}）`);
    });
});

常见问题说明 #

• 角色匹配优先使用固定角色ID查询，按名称匹配容易因服务器存在重名角色导致结果错误
• 如果遇到成员列表不全的情况，可在过滤逻辑前执行一次全量成员拉取：await hostGuild.members.fetch()，等待异步请求完成后再做缓存过滤
• 机器人需要在目标服务器内拥有「查看成员列表」权限，否则无法获取完整成员数据

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