Discord Webhook 怎么发 Embed 卡片消息?从 JSON 语法到 Python 实战避坑指南

2026年08月11日
📅 最后更新:2026年08月11日 | ✅ 本文由Discord技术编辑团队审核
发送 Discord Webhook Embed 卡片的本质,就是向 Webhook URL 发送一个包含 embeds 数组的 JSON POST 请求。每一个 Embed 对象包含 titledescriptioncolor(需将十六进制颜色转换为十进制整数)、fields 等字段。最快速的调试方法是先用在线可视化编辑器(如 Discohook 可视化调试工具)调好 JSON 结构,再通过 cURL 或 Python 请求库直接推送。
 Discord Webhook 发送 Embed

什么是 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 的三大硬核优势:
  1. 信息层级分明:支持字段并行排版(inline),关键指标一目了然。
  2. 视觉识别度极高:通过不同的侧边栏颜色线(如红色代表错误,绿色代表成功),团队成员无需细看文字就能秒懂消息级别。
  3. 原生 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 卡片底部小字 包含 texticon_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 的字段,强制换行逻辑也会被触发。

Discord Webhook 发送 Embed

代码实战:如何从零发送卡片消息

在代码调用之前,你需要先获取一个 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()
官方 API 的详细定义和所有高级参数可以查阅 Discord Developer Portal 官方文档,了解更多如 authorprovider 等接口细节。

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_urlimage.url 是否均采用 HTTPS 协议?
  • [ ] 社区安全:Webhook URL 是否误上传到了公开 GitHub 仓库?(如果泄漏,请立即在 Discord 频道内删除并重新创建)
更多关于 Discord 社区搭建与自动化工具的技巧,欢迎关注 Discords 社区

Discord Webhook 发送 Embed

FAQ 常见问题解答

Q1: 发送 Embed 消息时返回 HTTP 400 错误,该怎么排查?

A: 90% 的 400 错误由以下原因引起:
  1. color 传入了字符串(如 "#FF0000")而非整数。
  2. fields 数组中的对象缺少了必填的 namevalue 字段。
  3. 文本超过了字符限制(例如某个 field.value 超过了 1024 字符)。
  4. 时间戳格式不符合 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 怎么设置隐身?挂机打游戏不被打扰的 4 种隐身黑科技

电脑端最快路径:点击左下角头像 -> 选择“隐身 (Invis...

Discord 怎么用手机号加好友?2026 最新操作指南与通讯录同步避坑全攻略

Discord 无法直接在搜索框输入对方手机号添加好友。它不提供...

Discord Nitro 上传上限是多少?2026 快捷对比:Basic 与 Premium 文件传输规格详解

免费用户(Free): 单文件上传上限为 10 MB(2026年部...

Discord Webhook 怎么发 Embed 卡片消息?从 JSON 语法到 Python 实战避坑指南

发送 Discord Webhook Embed 卡片的本质,就是向 Webhook U...

如何在 Discord 实现 Markdown 排版?加粗、斜体、代码块与隐藏文字教学

Discord 内置了强大的 Markdown 支持,通过简单的符号包裹...

Discord 怎么设置隐藏频道?结合身份组权限,手把手教你打造 100% 私密的专属频道

隐藏 Discord 频道的核心逻辑极简单:把 @everyone 的“查看...