Discord API:开发者全指南 (2026)
通过代码示例从零开始构建 Discord 机器人与集成项目
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
Discord API:2026年完整开发者指南
Discord 拥有超过 2 亿月活跃用户,目前仍是游戏社区、开发者群体、内容创作者受众以及日益增长的企业团队的主导平台。通过 Discord API,你可以构建机器人来实现自动化管理、播放音乐、运行游戏、集成外部服务以及创建丰富的交互体验。
本指南将带你从零开始构建一个 Discord 机器人,涵盖环境配置、事件处理、斜杠命令(slash commands)、消息组件和部署。
前提条件
在开始之前,你需要准备:
- 一个 Discord 账号
- 一个拥有管理员权限的 Discord 服务器(用于测试)
- Node.js 18+ 或 Python 3.10+
- 基础编程知识
第 1 步:创建机器人应用
- 访问 Discord Developer Portal。
- 点击 "New Application" 并为其命名。
- 在左侧侧边栏中导航至 "Bot" 部分。
- 点击 "Reset Token" 生成机器人令牌(token)。请妥善保存此令牌——它只会显示一次。
- 在 "Privileged Gateway Intents" 下,启用以下项:
- Message Content Intent(如果你的机器人需要读取消息内容)
- Server Members Intent(如果你的机器人需要成员数据)
- Presence Intent(如果你的机器人需要追踪用户状态)
第 2 步:将机器人邀请至服务器
- 进入 "OAuth2" 栏目,然后点击 "URL Generator"。
- 在 "Scopes" 下,勾选
bot和applications.commands。 - 在 "Bot Permissions" 下,选择机器人所需的权限:
| 权限 | 适用场景 |
|---|---|
| Send Messages | 几乎所有场景 |
| Read Message History | 对过去的消息做出反应 |
| Manage Messages | 审核管理(删除消息) |
| Embed Links | 发送丰富的嵌入式消息 |
| Attach Files | 发送图片或文件 |
| Add Reactions | 基于反应的交互 |
| Manage Roles | 身份组分配机器人 |
| Kick/Ban Members | 审核管理机器人 |
| Use Slash Commands | 现代化的命令界面 |
- 复制生成的 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 机器人中。
