Discord API：开发者全指南 (2026)

Discord API：2026年完整开发者指南

Discord 拥有超过 2 亿月活跃用户，目前仍是游戏社区、开发者群体、内容创作者受众以及日益增长的企业团队的主导平台。通过 Discord API，你可以构建机器人来实现自动化管理、播放音乐、运行游戏、集成外部服务以及创建丰富的交互体验。

本指南将带你从零开始构建一个 Discord 机器人，涵盖环境配置、事件处理、斜杠命令（slash commands）、消息组件和部署。

前提条件

在开始之前，你需要准备：

• 一个 Discord 账号
• 一个拥有管理员权限的 Discord 服务器（用于测试）
• Node.js 18+ 或 Python 3.10+
• 基础编程知识

第 1 步：创建机器人应用

1. 访问 Discord Developer Portal。
2. 点击 "New Application" 并为其命名。
3. 在左侧侧边栏中导航至 "Bot" 部分。
4. 点击 "Reset Token" 生成机器人令牌（token）。请妥善保存此令牌——它只会显示一次。
5. 在 "Privileged Gateway Intents" 下，启用以下项：
   • Message Content Intent（如果你的机器人需要读取消息内容）
   • Server Members Intent（如果你的机器人需要成员数据）
   • Presence Intent（如果你的机器人需要追踪用户状态）

第 2 步：将机器人邀请至服务器

1. 进入 "OAuth2" 栏目，然后点击 "URL Generator"。
2. 在 "Scopes" 下，勾选 bot 和 applications.commands。
3. 在 "Bot Permissions" 下，选择机器人所需的权限：

权限	适用场景
Send Messages	几乎所有场景
Read Message History	对过去的消息做出反应
Manage Messages	审核管理（删除消息）
Embed Links	发送丰富的嵌入式消息
Attach Files	发送图片或文件
Add Reactions	基于反应的交互
Manage Roles	身份组分配机器人
Kick/Ban Members	审核管理机器人
Use Slash Commands	现代化的命令界面

4. 复制生成的 URL，并在浏览器中打开它，将机器人邀请到你的服务器。

第 3 步：项目初始化 (JavaScript)

初始化项目：

mkdir my-discord-bot && cd my-discord-bot
npm init -y
npm install discord.js dotenv

创建环境配置文件：

# .env
DISCORD_TOKEN=your_bot_token_here
CLIENT_ID=your_application_id_here
GUILD_ID=your_test_server_id_here

编写机器人主体文件：

// index.js
const { Client, GatewayIntentBits, Events } = require('discord.js');
require('dotenv').config();

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});

client.once(Events.ClientReady, (readyClient) => {
  console.log(`Bot is online as ${readyClient.user.tag}`);
});

client.on(Events.MessageCreate, (message) => {
  // 忽略来自机器人的消息
  if (message.author.bot) return;

  if (message.content === '!ping') {
    message.reply(`Pong! Latency: ${client.ws.ping}ms`);
  }
});

client.login(process.env.DISCORD_TOKEN);

运行你的机器人：

node index.js

第 3 步（替代方案）：使用 Python 初始化

mkdir my-discord-bot && cd my-discord-bot
python -m venv venv
source venv/bin/activate
pip install discord.py python-dotenv

# bot.py
import discord
from discord.ext import commands
import os
from dotenv import load_dotenv

load_dotenv()

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix="!", intents=intents)

@bot.event
async def on_ready():
    print(f"Bot is online as {bot.user}")

@bot.command()
async def ping(ctx):
    await ctx.reply(f"Pong! Latency: {round(bot.latency * 1000)}ms")

bot.run(os.getenv("DISCORD_TOKEN"))

python bot.py

第 4 步：注册斜杠命令 (Slash Commands)

斜杠命令是与 Discord 机器人交互的现代化方式。当用户输入 / 时，命令会显示在菜单中。

JavaScript (discord.js)：

// deploy-commands.js
const { REST, Routes, SlashCommandBuilder } = require('discord.js');
require('dotenv').config();

const commands = [
  new SlashCommandBuilder()
    .setName('ping')
    .setDescription('Check bot latency'),

  new SlashCommandBuilder()
    .setName('userinfo')
    .setDescription('Get information about a user')
    .addUserOption(option =>
      option.setName('user')
        .setDescription('The user to look up')
        .setRequired(false)
    ),

  new SlashCommandBuilder()
    .setName('poll')
    .setDescription('Create a simple poll')
    .addStringOption(option =>
      option.setName('question')
        .setDescription('The poll question')
        .setRequired(true)
    ),
].map(command => command.toJSON());

const rest = new REST().setToken(process.env.DISCORD_TOKEN);

(async () => {
  try {
    console.log('Registering slash commands...');
    await rest.put(
      Routes.applicationGuildCommands(
        process.env.CLIENT_ID,
        process.env.GUILD_ID
      ),
      { body: commands },
    );
    console.log('Slash commands registered successfully.');
  } catch (error) {
    console.error(error);
  }
})();

在机器人中处理斜杠命令：

// 添加到 index.js
const { EmbedBuilder } = require('discord.js');

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === 'ping') {
    await interaction.reply(`Pong! Latency: ${client.ws.ping}ms`);
  }

  if (interaction.commandName === 'userinfo') {
    const user = interaction.options.getUser('user') || interaction.user;
    const member = await interaction.guild.members.fetch(user.id);

    const embed = new EmbedBuilder()
      .setTitle(user.username)
      .setThumbnail(user.displayAvatarURL({ size: 256 }))
      .addFields(
        { name: 'ID', value: user.id, inline: true },
        { name: 'Joined Server', value: member.joinedAt.toDateString(), inline: true },
        { name: 'Account Created', value: user.createdAt.toDateString(), inline: true },
        { name: 'Roles', value: member.roles.cache.map(r => r.name).join(', ') }
      )
      .setColor(0x5865F2);

    await interaction.reply({ embeds: [embed] });
  }

  if (interaction.commandName === 'poll') {
    const question = interaction.options.getString('question');
    const pollMessage = await interaction.reply({
      content: `**Poll:** ${question}`,
      fetchReply: true,
    });
    await pollMessage.react('👍');
    await pollMessage.react('👎');
  }
});

第 5 步：添加交互式组件

Discord 支持按钮、选择菜单及模态框（modals）来实现丰富的交互：

const {
  ActionRowBuilder,
  ButtonBuilder,
  ButtonStyle,
  StringSelectMenuBuilder,
} = require('discord.js');

// 按钮示例
client.on(Events.InteractionCreate, async (interaction) => {
  if (interaction.commandName === 'ticket') {
    const row = new ActionRowBuilder().addComponents(
      new ButtonBuilder()
        .setCustomId('create_ticket')
        .setLabel('Create Support Ticket')
        .setStyle(ButtonStyle.Primary),
      new ButtonBuilder()
        .setCustomId('close_ticket')
        .setLabel('Close Ticket')
        .setStyle(ButtonStyle.Danger),
    );

    await interaction.reply({
      content: 'Need help? Create a support ticket:',
      components: [row],
    });
  }

  // 处理按钮点击
  if (interaction.isButton()) {
    if (interaction.customId === 'create_ticket') {
      await interaction.reply({
        content: 'Ticket created! A staff member will be with you shortly.',
        ephemeral: true,
      });
    }
  }
});

Discord API 频率限制 (Rate Limits)

Discord 执行严格的频率限制。了解这些限制可以防止你的机器人被封禁：

端点类型	频率限制
Global (全局)	50 次请求/秒
Per route (按路由)	各异 (查看 X-RateLimit-* 响应头)
Message send (每个频道)	5 条消息/5 秒
Bulk delete (批量删除)	1 次请求/1 秒
Guild member fetch	10 次请求/10 秒
Reaction add (添加反应)	1 次/0.25 秒

响应中的频率限制头：

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1738886400.000
X-RateLimit-Bucket: abc123

discord.js 和 discord.py 都会通过内置的队列系统自动处理频率限制。如果你直接使用 REST API，请针对 429 响应实现指数退避（exponential backoff）。

第 6 步：部署机器人

选项 1：VPS (推荐)

部署到任何 VPS 提供商（DigitalOcean, Hetzner, Linode），并使用进程管理器：

# 安装 PM2
npm install -g pm2

# 启动机器人
pm2 start index.js --name "discord-bot"

# 设置崩溃或重启后自动启动
pm2 startup
pm2 save

选项 2：Railway 或 Render

适用于类似无服务器（serverless）的部署方式：

# railway.toml
[build]
  builder = "nixpacks"

[deploy]
  startCommand = "node index.js"

将代码推送到 GitHub 并连接到 Railway 进行自动部署。

选项 3：Docker

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["node", "index.js"]

docker build -t discord-bot .
docker run -d --env-file .env --name discord-bot discord-bot

常见的机器人模式

模式	描述	应用场景
Moderation	自动删除、警告、禁言、封禁	社区管理
Welcome	欢迎新成员，分配身份组	入职引导
Reaction roles	根据反应分配身份组	自助式身份选择
Logging	追踪编辑、删除、加入/离开记录	审计审计
Music	在语音频道播放音频	娱乐体验
Economy	虚拟货币、商店、排行榜	提高活跃度
AI Chat	集成大语言模型（LLM）进行自然对话	支持、趣味交互

结论

Discord API 已经非常成熟，文档齐全，并拥有优秀的社区开发库支持。无论你是构建一个简单的管理机器人，还是复杂的交互式体验，斜杠命令、消息组件和事件驱动架构都能提供你所需的一切。

如果你的机器人需要 AI 生成媒体功能——例如创建自定义头像、为社区生成视频内容或添加 AI 语音功能——Hypereal AI 提供了高性价比的按需付费 API，涵盖图像生成、视频创建、数字人（talking avatars）以及语音克隆，你可以直接将其集成到你的 Discord 机器人中。