📅 最后更新:2026年08月11日 | ✅ 本文由Discord技术编辑团队审核
发送 Discord Webhook Embed 卡片的本质,就是向 Webhook URL 发送一个包含
embeds 数组的 JSON POST 请求。每一个 Embed 对象包含 title、description、color(需将十六进制颜色转换为十进制整数)、fields 等字段。最快速的调试方法是先用在线可视化编辑器(如 Discohook 可视化调试工具)调好 JSON 结构,再通过 cURL 或 Python 请求库直接推送。
什么是 Discord Embed?为什么你不该直接发纯文本?
在 Discord 里,普通 Webhook 消息就是一段字符串,而 Embed(嵌入卡片)则是带有左侧边框颜色线、独立高亮背景、标题、多列字段、缩略图和页脚的结构化富文本卡片。
JSON
{
"username": "系统监控助手",
"avatar_url": "https://i.imgur.com/AfFp7pu.png",
"content": "⚠️ 服务器节点触发高压告警!",
"embeds": [
{
"title": "CPU 负载超限通知",
"description": "节点 **us-east-1** 当前 CPU 使用率已连续 5 分钟超过 90%。",
"color": 15158332,
"fields": [
{
"name": "当前使用率",
"value": "94.2%",
"inline": true
},
{
"name": "影响服务",
"value": "API-Gateway",
"inline": true
}
],
"footer": {
"text": "监控服务 v2.4"
}
}
]
}
使用 Embed 的三大硬核优势:
-
信息层级分明:支持字段并行排版(
inline),关键指标一目了然。 -
视觉识别度极高:通过不同的侧边栏颜色线(如红色代表错误,绿色代表成功),团队成员无需细看文字就能秒懂消息级别。
-
原生 Markdown 支持:卡片内部全面支持 Markdown 语法。如果你对具体的样式细节不确定,可以参考我们之前整理的Discord Markdown 排版与格式化实操指南。
Discord Embed JSON 核心字段深度解析
Discord 官方 API 对 Embed 的字段限制非常严格。以下是最常调用的核心结构及踩坑点解析:
| 字段名 (Field) | 类型 (Type) | 作用说明 | 隐藏坑点与限制 |
title |
String | 卡片主标题 | 最长 256 字符,不支持复杂的 HTML |
description |
String | 卡片正文描述 | 最长 4000 字符,支持大部分 Markdown |
color |
Integer | 卡片左侧彩色边框线 | 必须传入十进制整数,不能写 #FF0000 字符串! |
fields |
Array of Objects | 多列并行字段列表 | 最多 25 个,每个包含 name, value, inline |
timestamp |
String | 显示在 Footer 旁边的时间 | 必须是符合 ISO 8601 标准的时间字符串 |
footer |
Object | 卡片底部小字 | 包含 text 和 icon_url |
image / thumbnail |
Object | 大图 / 右上角缩略图 | 必须是公网可直接访问的 HTTPS 图片链接 |
🛑 踩坑预警 1:十六进制颜色转换十进制
这是新手最容易报错
400 Bad Request 的地方。假设你在设计工具里看中的颜色是 #E74C3C(红色):-
❌ 错误写法:
"color": "#E74C3C"或"color": "0xE74C3C" -
✅ 正确写法:在 Python 中使用
int("E74C3C", 16)计算得出15158332,JSON 中填入"color": 15158332。
🛑 踩坑预警 2:Inline 字段同行显示规则
fields 里的 inline: true 可以让多个小字段横向并排显示。但 Discord 的渲染机制是:一行最多放置 3 个 inline 字段。如果超过 3 个,第 4 个会自动折行;如果在 inline 字段之间插入了一个 inline: false 的字段,强制换行逻辑也会被触发。代码实战:如何从零发送卡片消息
在代码调用之前,你需要先获取一个 Webhook 链接。如果你还不清楚如何在特定频道创建 Webhook,或者想控制哪些身份组能看到这些卡片,可以先了解 Discord 隐藏频道与权限组设置,确保接口暴露在有权限管控的安全频道中。
方法一:用 cURL 在命令行快速测试
打开你的终端,直接复制以下命令(记得替换
YOUR_WEBHOOK_URL):Bash
curl -H "Content-Type: application/json" \
-X POST \
-d '{
"username": "部署机器人",
"embeds": [
{
"title": "🚀 生产环境部署成功",
"description": "服务 `v1.2.0` 已成功上线至集群。",
"color": 3066993,
"fields": [
{
"name": "分支",
"value": "`main`",
"inline": true
},
{
"name": "耗时",
"value": "45s",
"inline": true
}
]
}
]
}' \
YOUR_WEBHOOK_URL
方法二:Python 脚本(无需额外第三方 SDK)
使用 Python 标准库
urllib.request 即可实现,不依赖外部包:Python
import json
import urllib.request
from datetime import datetime
WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
def send_discord_embed():
payload = {
"username": "AlertManager",
"embeds": [
{
"title": "数据库连接池异常",
"description": "检测到主数据库连接超时,已自动切换至从库。",
"color": int("F1C40F", 16), # 黄色警告, 自动转十进制
"timestamp": datetime.utcnow().isoformat() + "Z", # ISO 8601 格式
"fields": [
{"name": "响应时间", "value": "5200ms", "inline": True},
{"name": "当前连接数", "value": "128/150", "inline": True}
],
"footer": {
"text": "集群监控系统"
}
}
]
}
req = urllib.request.Request(
WEBHOOK_URL,
data=json.dumps(payload).encode('utf-8'),
headers={'Content-Type': 'application/json', 'User-Agent': 'Mozilla/5.0'}
)
try:
with urllib.request.urlopen(req) as response:
if response.status == 204:
print("Embed 消息发送成功!")
except Exception as e:
print(f"发送失败: {e}")
if __name__ == "__main__":
send_discord_embed()
Discord Webhook 实战 SOP 检查清单
在将 Webhook 部署到生产环境之前,建议逐项比对该 Checklist,避免线上脚本崩溃:
-
[ ] 请求头校验:是否设置了
'Content-Type': 'application/json'? -
[ ] 颜色格式:
color字段是否已转为十进制整数?(非 Hex 字符串) -
[ ] 字符上限检查:
-
title<= 256 字符 -
description<= 4000 字符 -
单个
field.name<= 256 字符,field.value<= 1024 字符 -
所有 Embed 字段总字数单条消息不超过 6000 字符
-
-
[ ] 频率控制 (Rate Limit):高频推送脚本是否处理了 HTTP
429 Too Many Requests?(Discord 对单个 Webhook 限制为 5 秒内最多 30 次请求) -
[ ] URL 格式:
avatar_url和image.url是否均采用 HTTPS 协议? -
[ ] 社区安全:Webhook URL 是否误上传到了公开 GitHub 仓库?(如果泄漏,请立即在 Discord 频道内删除并重新创建)
更多关于 Discord 社区搭建与自动化工具的技巧,欢迎关注 Discords 社区。
FAQ 常见问题解答
Q1: 发送 Embed 消息时返回 HTTP 400 错误,该怎么排查?
A: 90% 的 400 错误由以下原因引起:
-
color传入了字符串(如"#FF0000")而非整数。 -
fields数组中的对象缺少了必填的name或value字段。 -
文本超过了字符限制(例如某个
field.value超过了 1024 字符)。 -
时间戳格式不符合 ISO 8601 标准。
Q2: 一个 Webhook 请求里可以同时发送多张 Embed 卡片吗?
A: 可以。
embeds 是一个数组,你可以在一次 POST 请求中传入最多 10 个 Embed 对象。它们会在同一个消息块中连续呈现,适合一次性推送到多个维度的统计数据。Q3: 如何在 Embed 卡片里艾特(@)某个用户或身份组?
A: 将艾特文本(例如
<@USER_ID> 或 <@&ROLE_ID>)放在顶级 content 字段或 Embed 的 description / field.value 中均可解析。但需要注意:如果是通过普通 Webhook 发送,必须确保 Webhook 没有被取消 Mention Everyone 权限。D
Discord技术编辑团队
Discord使用教程与技术支持团队
Discord使用教程与技术支持团队
本文由Discord技术编辑团队撰写和审核。我们持续跟踪Discord平台更新,为您提供最新的使用教程、服务器搭建指南、机器人配置方法和问题解决方案。如有疑问,欢迎在评论区留言。
📌 本文内容基于Discord官方文档和实际测试编写,转载请注明出处。


