Discord.NET 教程示例Bot运行后始终离线无法上线问题求助

问题表现 #

• 程序在编辑器中无语法报错，编译、运行阶段未抛出异常
• 控制台正常输出启动日志
• Discord服务器内Bot始终处于离线状态，头像旁显示灰色状态圈，归类在用户列表离线分组

环境与前置信息 #

• 代码基于Discord.NET官方入门指南编写，仅做少量自定义修改
• 已确认Bot Token配置正确，对应旧应用已重新生成全新Token用于测试
• 开发环境为Windows 10，通过Visual Studio通用平台控制台应用模板创建项目

问题复现代码 #

using Discord;
using Discord.WebSocket;

using System.Text.Json;
using System.Text;

namespace Mai
{
    class Program
    {
        private DiscordSocketClient _client;
        private Dictionary<string, string> _config;

        static void Main(string[] args) => new Program().MainAsync().GetAwaiter().GetResult();
        public async Task MainAsync()
        {
            Console.WriteLine("Mai, starting up!");
            await LoadConfigurationFile();

            Console.WriteLine("Okay, I'm making my client now! I'll also add the logger to it!");
            _client = new DiscordSocketClient(
                new DiscordSocketConfig()
                {
                    LogLevel = LogSeverity.Debug
                }
            );
            _client.Log += Log;

            Console.WriteLine("Logging in and starting the client!");
            await _client.LoginAsync(TokenType.Bot, _config["Token"]);
            await _client.StartAsync();

            Console.WriteLine("I'm all set up! I'll keep working until the console is closed!");
            await Task.Delay(-1);
        }

        # region Methods

        public Task Log(LogMessage msg)
        {
            Console.WriteLine(msg.ToString());
            return Task.CompletedTask;
        } // End of method Log

        public Task LoadConfigurationFile()
        {
            using (FileStream openStream = File.OpenRead("config.json"))
            {
                _config = JsonSerializer.Deserialize<Dictionary<String, String>>(openStream);
            };
            return Task.CompletedTask;
        } // End of method LoadConfigurationFile

        #endregion Methods

    } // End of class program

} // End of namespace Mai

运行日志截图 #

根因定位与修复方案 #

核心原因：未配置网关意向（GatewayIntents） #

Discord API v9及以上版本强制要求客户端在建立连接时声明所需使用的网关意向，未配置的情况下，LoginAsync和StartAsync方法不会抛出显性异常，但客户端无法完成网关握手流程，自然不会同步在线状态、接收服务端事件。
当前代码初始化DiscordSocketClient时仅配置了日志等级，未指定GatewayIntents，是导致离线的最常见原因。
修复方式为修改客户端初始化配置，按需声明需要的意向：

_client = new DiscordSocketClient(
    new DiscordSocketConfig()
    {
        LogLevel = LogSeverity.Debug,
        // 基础上线必须配置Guilds意向，其余意向按功能需求添加
        GatewayIntents = GatewayIntents.Guilds | GatewayIntents.GuildMessages | GatewayIntents.MessageContent
    }
);

注意：MessageContent、GuildPresences、GuildMembers属于特权意向，仅在代码中配置无法生效，必须到Discord开发者后台对应应用的Bot设置页，下滑到Privileged Gateway Intents板块，手动开启对应意向的开关后保存，否则网关会直接拒绝连接。

其他排查项 #

1. 旧应用权限兼容问题：创建时间较早的Discord应用默认会关闭所有特权意向开关，即便代码没有用到相关功能，也建议先检查后台意向开关状态，避免默认配置拦截连接。
2. 邀请链接校验：确认Bot加入服务器时使用的邀请链接scope包含bot参数，权限配置不足也会导致状态异常。
3. 连接状态校验：可以给_client.Ready事件加日志输出，如果程序启动后始终没有触发Ready事件，即可确认网关连接未建立成功，优先排查意向配置与网络连通性。

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