Discord JDA开发 Kick踢人命令抛出异常无法正常执行

云上老周

2026-8-30

问题根因

两类异常和回退代码后仍复现的问题本质都是代码执行顺序错误+缺失前置边界校验，和你新增/删除的业务逻辑无关：

java.lang.IllegalStateException: This message event did not happen in a guild：你的监听器没有过滤消息来源，JDA默认会全局接收所有频道消息（包括用户给机器人发的私信），私信场景下事件不携带服务器（Guild）实例，直接调用event.getGuild()就会抛出该异常。你早期测试时只在服务器频道发命令所以没触发，一旦有用户在私信触发过一次命令，就会持续抛错。
java.lang.IndexOutOfBoundsException: Index 0 out of bounds for length 0：你在获取被@的成员前没有做非空判断，当用户发送u!kick但没有@任何成员时，getMentions().getMembers()返回长度为0的空列表，直接调用get(0)必然触发越界。
回退代码仍复现的核心原因：你把上述两个会抛异常的取值操作写在了所有校验逻辑（权限校验、参数校验、来源校验）的前面，只要请求不符合前置要求，代码根本走不到你写的校验逻辑，直接在取值行就崩溃，哪怕你回退到早期版本，只要执行顺序没改，问题就会一直存在。

修复方案

严格按照「先校验过滤、后取值执行业务」的顺序调整代码，所有可能抛出异常的取值操作必须放在对应校验通过之后，以下是可直接替换的完整实现（适配JDA 5.0.0-alpha.4版本）：

import net.dv8tion.jda.api.EmbedBuilder;
import net.dv8tion.jda.api.Permission;
import net.dv8tion.jda.api.entities.Guild;
import net.dv8tion.jda.api.entities.Member;
import net.dv8tion.jda.api.entities.TextChannel;
import net.dv8tion.jda.api.events.message.MessageReceivedEvent;
import net.dv8tion.jda.api.hooks.ListenerAdapter;
import java.awt.*;
import java.time.OffsetDateTime;
import java.util.List;

public class Kick extends ListenerAdapter {
    private static final String CMD_PREFIX = "u!";
    private static final long LOG_CHANNEL_ID = 984832326947197008L;

    @Override
    public void onMessageReceived(MessageReceivedEvent event) {
        // 过滤机器人自身消息，避免自触发死循环
        if (event.getAuthor().isBot()) return;
        String content = event.getMessage().getContentRaw();
        // 前缀不匹配直接终止，不执行后续逻辑
        if (!content.startsWith(CMD_PREFIX + "kick")) return;

        // 1. 优先校验消息来源，从根源解决Guild上下文缺失异常
        if (!event.isFromGuild()) {
            event.getChannel().sendMessage("踢人命令仅支持在服务器内使用").queue();
            return;
        }
        Guild guild = event.getGuild();
        Member operator = event.getMember();

        // 2. 校验操作者权限
        if (operator == null || !operator.hasPermission(Permission.KICK_MEMBERS)) {
            event.getChannel().sendMessage("你没有执行踢人操作的权限").queue();
            return;
        }

        // 3. 校验被提及成员，从根源解决列表越界异常
        List<Member> mentioned = event.getMessage().getMentions().getMembers();
        if (mentioned.isEmpty()) {
            event.getChannel().sendMessage("命令格式错误，正确用法：`u!kick @用户 [踢人原因]`").queue();
            return;
        }
        Member target = mentioned.get(0);

        // 4. 补充边界校验，避免逻辑漏洞
        if (target.equals(operator)) {
            event.getChannel().sendMessage("不能将你自己踢出服务器").queue();
            return;
        }
        if (!guild.getSelfMember().canInteract(target)) {
            event.getChannel().sendMessage("机器人权限不足，无法踢出该用户（对方身份组优先级高于机器人）").queue();
            return;
        }
        if (!operator.canInteract(target)) {
            event.getChannel().sendMessage("你无法踢出该用户（对方身份组优先级高于你）").queue();
            return;
        }

        // 解析踢人原因
        String reason = content.replace(CMD_PREFIX + "kick", "")
                .replace("<@!" + target.getIdLong() + ">", "")
                .trim();
        if (reason.isBlank()) reason = "未填写操作原因";
        String finalReason = reason;

        // 先发送私信通知（踢人后成员会离开服务器，无法再获取私信通道）
        target.getUser().openPrivateChannel()
                .flatMap(pm -> pm.sendMessage("你已被踢出服务器【" + guild.getName() + "】，操作原因：" + finalReason))
                .onErrorMap(e -> null) // 静默忽略用户关闭私信的异常，不中断后续流程
                .queue();

        // 执行踢人操作
        guild.kick(target, finalReason).queue(v -> {
            // 回复命令执行结果
            event.getChannel().sendMessage("已成功踢出用户 " + target.getAsMention() + "，原因：" + finalReason).queue();
            // 推送操作日志
            TextChannel logChannel = guild.getTextChannelById(LOG_CHANNEL_ID);
            if (logChannel != null && guild.getSelfMember().hasPermission(logChannel, Permission.MESSAGE_SEND, Permission.MESSAGE_EMBED_LINKS)) {
                EmbedBuilder logEmbed = new EmbedBuilder()
                        .setTitle("踢人操作日志")
                        .setColor(Color.RED)
                        .addField("操作者", operator.getAsMention(), true)
                        .addField("被踢用户", target.getAsMention(), true)
                        .addField("操作原因", finalReason, false)
                        .setTimestamp(OffsetDateTime.now());
                logChannel.sendMessageEmbeds(logEmbed.build()).queue();
            }
        }, e -> event.getChannel().sendMessage("踢人失败：" + e.getMessage()).queue());
    }
}

避坑提示

JDA 5.x alpha版本的MessageReceivedEvent默认覆盖私信、服务器频道、线程三类场景，所有服务器专属命令必须第一时间加event.isFromGuild()判断过滤非服务器请求。
所有调用List.get(index)的场景，必须提前判断列表长度/是否为空，不要默认用户会按照要求的格式输入命令参数。
涉及权限的操作（踢人、封禁、修改身份组）必须同时校验操作者和机器人自身的权限优先级，避免出现权限不足的运行时异常。
异步操作（发私信、踢人、发消息）统一用queue()非阻塞方法，不要用complete()阻塞事件线程，否则会导致机器人响应卡顿。

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