oEmbed接口必须通过link标签声明，meta标签无效；规范要求使用<link rel="alternate" type="application/json+oembed">暴露endpoint，客户端仅识别link且忽略meta，同时服务端需严格满足Content-Type、url校验和响应字段三大条件。
oEmbed 接口必须通过 link 标签声明，meta 标签无效
HTML 的 meta 标签无法用于声明 oEmbed 动态卡片解析接口——这是常见误解。oEmbed 规范（oembed.com）明确要求服务端提供者或资源发布方使用 <link rel="alternate" type="application/json+oembed">（或 application/xml+oembed）来暴露 endpoint，浏览器和平台（如 Twitter、Slack、Discord）只识别这类 link 标签，完全忽略 meta。
如果你在 <head> 里写了类似这样的代码，它不会被任何 oEmbed 消费者读取：
<meta name="oembed" content="https://api.example.com/oembed?url=%s">
这不是浏览器限制，而是 oEmbed 客户端（比如 Mastodon 的链接预览模块）的解析逻辑本身就不扫描 meta。
正确声明 oEmbed endpoint 的 link 写法
必须在页面 <head> 中添加一个或多个 <link> 标签，每个对应一种响应格式，并确保 href 是可公开访问、支持 GET 请求、能正确返回 JSON/XML 的 endpoint。
立即学习“前端免费学习笔记（深入）”；
-
rel值只能是alternate，不可写成oembed或其他自定义值 -
type必须严格为application/json+oembed或application/xml+oembed -
href中的 URL 需已 URL 编码（特别是含查询参数时），例如：https://api.example.com/oembed?url=https%3A%2F%2Fexample.com%2Fpost%2F123 - 如果同一页面支持多种格式，可以并列多个
link，客户端通常优先选 JSON
示例：
<link rel="alternate" type="application/json+oembed" href="https://api.example.com/oembed?url=https%3A%2F%2Fexample.com%2Fpost%2F123&format=json"> <link rel="alternate" type="application/xml+oembed" href="https://api.example.com/oembed?url=https%3A%2F%2Fexample.com%2Fpost%2F123&format=xml">
服务端 endpoint 必须满足的三个硬性条件
即使前端 link 写对了，若后端不配合，卡片仍不会渲染。常见失败原因集中在以下三点：
- 响应头缺失
Content-Type: application/json+oembed（JSON 方式）或application/xml+oembed（XML 方式），仅靠 body 格式不够 - 未正确处理
url参数：必须校验该 URL 是否属于本域（或白名单），且不能直接反射未经校验的输入，否则会触发安全拦截（如 Slack 拒绝解析） - 返回字段缺失必要项：至少包含
type、version、title（type为link或rich）、html（仅rich类型必需）或url（photo类型必需）
一个最小可用 JSON 响应示例（type: "link"）：
{
"version": "1.0",
"type": "link",
"title": "一篇技术笔记",
"url": "https://example.com/post/123"
}
调试 oEmbed 解析失败的实操路径
别依赖“发链接看预览”这种黑盒方式。要快速定位问题，按顺序检查：
- 用 curl 直接请求
link标签里的hrefURL，确认 HTTP 状态码是 200，且响应体可读 - 检查响应头中是否存在
Content-Type，值是否精确匹配application/json+oembed（注意：不是application/json） - 把该 URL 粘贴到官方验证工具（如 oembed.com validator）里测试；它会报出字段缺失、类型错误等细节
- 某些平台（如 Discord）会缓存 oEmbed 结果，修改后需用新 URL 或加时间戳参数（如
&t=1712345678）绕过缓存
最常被忽略的是响应头的 Content-Type —— 很多开发者只关注 JSON 结构，却忘了设对 MIME 类型，导致平台静默丢弃响应。
