X（Twitter）嵌入代码生成器

简介

Toollect 的 X（Twitter）嵌入代码生成器能把任意推文 URL 转换为 X 为在其他网站显示推文而发布的官方嵌入代码——twitter-tweet blockquote 加 widgets.js——一键完成，拷贝前有实时预览，并提供 X 自家界面的全部显示选项。粘贴链接、选择选项、预览、拷贝、粘贴。整个流程只需几秒。

它消除的摩擦，凡是手动嵌过推文的人都熟悉。X 自家的发布对话框虽然产出了代码，却把各种选择分散在不同画面里，不提供隐藏媒体和对齐的控制，对视频嵌入更是完全没有数值化的宽度调节。手写 blockquote 直到某个属性拼错、推文永远变成一个裸链接为止都还算顺利。本工具按照 widgets.js 期望的方式逐字组装标记，把你的选项翻译成正确的 data-* 属性，并在任何东西抵达你的页面之前展示真实渲染效果。

生成器在一条标签列后面提供两种模式。推文为任意帖子构建经典卡片——文字、照片、链接预览俱全——包含主题、220 至 550 像素的宽度、界面语言、对齐、对话与媒体的可见性、Do Not Track，以及省略共享脚本标签的选项。视频为同一则帖子做播放器优先的优化，把最高 1920 像素的宽度写入大型视频理应拥有的 data-media-max-width 属性。两种模式直接与 X 的公开 oEmbed 端点通信——无需 API 密钥、无需注册，中间也没有 Toollect 服务器。

使用场景

嵌入 X 内容出现的地方比博客文章多得多，两种模式自然地分担了这些工作。

博客与编辑内容

引用公众人物言论的评论文章、嵌入公告推文的技术文章、放上精彩瞬间视频的运动博客——都是经典场景。默认设置的推文模式涵盖文字推文；当帖子主体是一段视频、播放器应当占据整个栏宽时，切换到视频模式。

新闻编辑室与实时报道

记者会把目击者帖子和官方声明纳入持续报道中。速度重要，核验同样重要——无论现场联系人分享的是带追踪参数的应用程序分享链接、旧版 twitter.com 形式还是照片查看变体，生成器都会将其规范化为一个指向该推文的规范参照，并且在稿件发出前由预览确认推文仍可渲染。「隐藏对话」让串内容聚焦在被引用的那则声明上，而不是其上方的争论。

文档与技术写作

版本说明、更新日志和教程越来越多地引用工程师的推文串作为一手来源。「隐藏媒体」把链接预览折叠成纯文字以获得更安静的阅读体验，语言选择器以文档语言呈现操作按钮和时间戳，「省略脚本」让已经全局加载 widgets.js 的页面——组件库、文档主题——免于重复的脚本标签。

行销网站与作品集

客户好评推文作为社会证明、创办人推文串作为品牌故事。置中对齐把单条推荐语安放进狭窄字段；Do Not Track 向欧洲用户传递尊重隐私的信号；每张卡片上架前都经预览确认。

工作原理

工具分四步运行：

1. 解析并规范化 URL —— 输入会与 X 推文链接语法比对：一个用户名（不含 @，1–15 个字母、数字或底线）、status 路由、位于 x.com 或 twitter.com（可带 www./mobile./m. 前缀）上的 15–19 位 snowflake ID。像 ?s=20&t=… 这样的查找参数会被忽略而非清理——重建后的规范 URL 根本永远不会包含它们。网页客户端那些没有用户名的路由如 /i/web/status/… 会被拒绝并给出专门提示，因为 oEmbed 端点无法解析它们。
2. 创建官方请求 —— 你的选项成为 X 公开 oEmbed 端点（publish.x.com/oembed?url=…）上的查找参数：maxwidth、theme、lang、hide_thread、hide_media、align、dnt、omit_script。该端点免密钥且刻意不限速——它存在的意义正是让 CMS 把 URL 转换成嵌入。
3. 取得官方标记 —— 恰好一次 HTTPS GET 传回按 X 原样格式化的 blockquote HTML，你的选项已作为 data-* 属性烘焙其中。你的浏览器直接与 X 对话；没有任何 Toollect 服务器碰触这个请求。
4. 后处理并预览 —— 服务器传回的 script 标签被剥离并单独管理（这样无论你重新产生多少次，预览都只加载一次 widgets.js），视频模式会在客户端重写宽度属性（原因见下文），blockquote 进入预览区域。工具监视渲染出来的 iframe，若始终未出现便如实报告。

任何选项变更都会重跑整条链路——新请求、新标记、重渲染的预览——因此你拷贝的代码永远与眼前所见一致。

支持的 URL 格式

生成器接受每一种「带用户名标识一条推文」的 URL 形态，其余一律拒绝并给出具体提示。

接受的格式

推文 ID 之后的查看变体和垃圾参数会被直接忽略——嵌入始终指向推文本身，媒体由它自行渲染。https:// 前缀和结尾斜杠皆可省略。

拒绝的格式

/i/web/status/… 下无用户名的情况值得强调，因为它是最常见的意外。当你没有打开推文就直接从网页客户端拷贝其 URL 时，X 给出的就是这种形态。生成器刻意拒绝它——传给端点只会得到静默失败——并要求你使用完整链接。如果你想修复 URL 而不是重新拷贝，本站的 X（Twitter）链接解析器可以把这类链接解析成规范形式。

嵌入代码的结构

输出与 X 自家机制产生的代码一致，并已应用你的选项。默认设置下的推文嵌入如下所示（内容有删节）：

<blockquote class="twitter-tweet" data-width="550">
  <p lang="en" dir="ltr">Just setting up my twttr</p>
  &mdash; Jack (@jack)
  <a href="https://x.com/jack/status/20?ref_src=twsrc%5Etfw">2006年3月21日</a>
</blockquote>
<script async src="https://platform.x.com/widgets.js" charset="utf-8"></script>

逐一说明：

• blockquote 的类别 —— twitter-tweet 是 widgets.js 搜索的挂钩。页面上每个带此类别的元素都会变成一张渲染后的卡片。
• data-width（推文）—— 以像素计的最大渲染宽度。无论写入什么值，X 都会在内部将其压缩到约 250–550，所以生成器把你选的值保持在诚实区间内。
• data-media-max-width（视频）—— 媒体在卡片内允许展开的最大宽度，最高 1920 像素。仅视频模式存在——为什么生成器要亲自写这个属性，见「推文与视频嵌入」一章。
• data-theme="dark" —— 仅在选中深色时存在。以深色卡片外观渲染暗底亮字。
• data-lang —— 只要选了具体语言就存在（含英语）。在地化 widget 自身的字符串——时间戳格式、「阅读更多」过渡、操作按钮文案——但绝不会改动推文正文本身。只有「自动」省略该属性，此时 widgets.js 回退到宿主页面的语言。
• data-conversation="none" —— 由回复推文上的「隐藏对话」添加。没有它时，widgets.js 会在前面折叠展示父级推文的摘要。
• data-cards="hidden" —— 由「隐藏媒体」添加。链接预览、照片和视频保持折叠；只有文字会渲染。
• data-align —— 让卡片相对其容器向左或向右浮动，或置中。对齐为「无」时不出现。
• data-dnt="true" —— 由「退出个人化」添加。告知 X 不要将此嵌入及其页面浏览用于个人化推荐或个人化广告。
• 带署名行的段落 —— widgets.js 运行前可见的内容：推文文字、作者，以及指向该帖的链接。对于禁用 JavaScript 或脚本被封锁的访客来说这是永久体验，并会优雅降级为普通引用。
• script 标签 —— 来自 platform.x.com 的 widgets.js，异步加载。一页放一个就足以支撑任意数量的嵌入——这正是「省略脚本」选项的用武之地。

推文与视频嵌入

两个分页，同一条推文，两种不同的工作。切换标签页立即重新产生——不存在过期状态。

为什么工具要亲自写 data-media-max-width？因为 X 的 oEmbed 端点做不到。实测确认：端点会把每一个 maxwidth 参数——包括带视频的推文——压进 220–550 的推文区间，并且从不输出视频嵌入携带的 data-media-max-width 属性。该属性属于 publish.x.com 内部的流程——Embedded Video 生成器在那里事后装饰标记。本生成器精确复刻了这一装饰：剥掉服务器传回的被压缩的 data-width，把你选的宽度写进 data-media-max-width，于是一条 1200 像素的视频嵌入在你的页面上就真的是 1200 像素宽。

实际决策规则很简单。如果这条推文作为卡片阅读体验良好——用推文。如果把播放器拿掉它就空了——用视频，并给播放器留足空间。

嵌入选项

每个控件对应一个属性或一个请求参数。括号内为默认值。

语言（默认：页面语言）—— 提供「自动」与 X 为 widget 文案准备的 34 种语言。只要选了具体语言（含英语），就会作为 lang 参数发送并写入 data-lang——无论代码贴到哪里，widget 外壳都保持同一语言。它在地化的是围绕推文的时间戳和操作按钮文案，绝不是推文的文字。「自动」同时省略参数与属性——widgets.js 会以宿主页面声明的语言渲染；适合多语言网站，但输出会随粘贴位置而变。

主题（浅色，仅推文标签页）—— 深色发送 theme=dark 并写入 data-theme="dark"。浅色即不存在该属性。

宽度（推文 550，视频 560）—— 以精确数字输入，字段一失去焦点就会被收敛到有效区间。推文发送 maxwidth；视频驱动 data-media-max-width 的客户端重写。超出某分页区间的值活不过输入框——推文中输入 9999 会变成 550，视频中输入 100 会变成 560。

对齐（无）—— 靠左、靠右或置中会向请求写入 align、向 blockquote 写入 data-align。置中是在宽文章中安置单张卡片的不张扬做法；靠右让正文绕排。

隐藏对话（关，仅推文标签页）—— 发送 hide_thread=true，服务器将其翻译为 data-conversation="none"。只对回复有意义；对独立推文没有任何作用。

隐藏媒体（关，仅推文标签页）—— 发送 hide_media=true，翻译为 data-cards="hidden"。嵌入变成一段纯粹的引文。

省略 widgets.js 脚本标签（关）—— 发送 omit_script=true 并抑制输出中的 script 标签。适用于已在全站加载过 widgets.js 的网站——多个嵌入共用一个脚本。如果你的页面没有 widgets.js，请保持关闭；只有 blockquote 的话它会永远渲染为静态文字。

退出 X 个人化（关）—— 发送 dnt=true 并写入 data-dnt="true"。X 文档说明这会让嵌入及其所在页面不被用于个人化推荐和个人化广告。

使用方法

1. 粘贴推文 URL 到输入栏——上表中任意接受的格式。
2. 按下产生（或 Enter）。代码出现在输出框中，预览自动打开并显示 X 的真实渲染。
3. 选择标签页——标准卡片用推文，视频主导的推文用视频。切换即按该分页的选项和宽度区间重新产生。
4. 调整选项——语言、主题、宽度、对齐、各可见性勾选框。每次更改都会重新请求并重新渲染；代码框永远不会偏离预览。
5. 检查诊断信息——如果没有出现卡片，输出上方的警告会告诉你是 X 的脚本被拦截了还是这条推文无法嵌入。
6. 拷贝代码，贴到页面 HTML 中希望推文出现的位置。

不符合任何受支持格式的输入会清空输出并自我解释——要么是无效链接提示，要么（对无用户名的路由）要求提供完整链接。清除按钮一步重置输入、代码与预览。

教程

跟着一条真实链接走完两个分页。

第 1 步——粘贴应用程序分享链接。 拷贝行动应用程序分享出来的推文 URL，连追踪参数一起：

https://twitter.com/new27brigade/status/2090248985391014324?s=20&t=FakeNonce

按下产生。解析器越过旧网域和 s、t 参数直抵推文本身——new27brigade、status 2090248985391014324——产生的代码指向规范形式。预览打开，卡片渲染出来。

第 2 步——调暗。 把主题设为深色。代码获得 data-theme="dark"，预览以深色调重新渲染。注意这次重新请求——主题是服务器端烘焙的，所以每次选项变更都会再次调用端点，而不是在本机修改字符串。

第 3 步——收窄。 在宽度中输入 350 并按 Enter。属性变为 data-width="350"，卡片收缩。试着输入 9999 再点击别处——输入框弹回 550，反正 X 在那里也会压缩。

第 4 步——在地化界面。 把语言设为日语（日本语）。代码获得 data-lang="ja"，预览中的时间戳按日式惯例重新格式化。推文正文保持原样——这项设置只管 X 自己的标签文案。

第 5 步——切到视频。 点击视频标签页。工具以视频参数集重新请求并改写标记：data-width 消失，data-media-max-width="560" 出现，主题选择器从面板中隐去。把宽度拖到 1200——播放器随之扩张。这条推文是一段军事演习视频，视频模式正合适；若是文字公告你就会切回去。

第 6 步——拷贝交付。 点拷贝，贴到一个简单的 HTML 页面。打开它——播放器以全宽渲染。这就是完整的契约：同样的代码、同样的渲染，出现在你的页面上。

预览与诊断

预览针对你确切的 blockquote 运行 X 真正的 widgets.js，因此它失败的位置就是你页面将失败的位置。两则警告，两种不同意义：

两则警告都只在充裕的等待之后触发——脚本下载 20 秒、渲染再等 15 秒——慢速连接不会引发误报。可嵌入的推文远在这些窗口之内就会渲染完成。

一个值得一提的机制细节：首次产生会下载 widgets.js 并在整个工作阶段期间保留。之后的重新产生——新选项、分页切换——复用它并请它处理新的 blockquote，所以后续预览出现得比第一次更快。

专业提示

• 与链接解析器搭配使用。 解析器负责分析和清理链接——类型、snowflake ID、追踪键；生成器把干净的链接变成代码。用解析器归档，用生成器发布。
• 一个脚本标签，多个嵌入。 有多条推文的页面应全局加载一次 widgets.js——除第一份输出外全部勾选「省略脚本」，或者在网站范本中自行加载然后处处省略。
• 隐藏媒体让推文变成引文。 对于链接预览会喧宾夺主的编辑性引用，「隐藏媒体」加「隐藏对话」只剩文字和署名。
• 单条推荐语用置中。 宽版面里的置中对齐读起来是有意为之的设计；所有 CMS 默认的靠左很少是行销页面想要的。
• 让 widget 语言匹配页面语言。 日文页面上顶着英文 RETWEET 按钮显得未完工——具体语言的选择固定了外壳文案（正是你要负责的部分）；若同一份嵌入要在多语言模板间共用，改选「自动」，让 widgets.js 跟随各个宿主页面。
• 面向欧盟的页面打开 Do Not Track。 这个旗标由 X 官方文档定义并随嵌入传播——一键即可表明卡片尊重访客隐私。
• 先为字段设计，再定宽度。 推文物理上止步于 550 像素；在你做出承诺之前，预览会按容器尺寸展示真实结果。

替代方案

还有什么方法能把推文放上页面？

X 自家的分享对话框是最接近的替代品，也是同一个 blockquote 的出处——但它的客制止步于语言、隐藏对话、退出个人化和粗粒度的视频尺寸，没有通往 hide_media、align 或精确 maxwidth 的路径。API 路线花钱买来完全控制权，渲染仍然得自己做。第三方服务夹带它们自己的脚本。本生成器占据实用的中间地带——官方标记、完整选项、实时视觉确认。

与官方 API 对比

有三处官方界面涉及推文嵌入，本生成器直接构建在最友好的一处之上。

生成器严格按文档调用 oEmbed 端点——CMS 插件发出的也是同一个请求，只是这次由你的浏览器发出。它补上了端点缺少的东西：输入规范化、视频模式的 data-media-max-width 装饰、脚本标签管理和诊断。X API v2 被刻意排除在外——自 2026 年 2 月的定价改革取消免费额度以来，经由它读取推文意味着为嵌入用途本已由免费端点覆盖的能力付费。

嵌入代码生成器与链接解析器的区别

Toollect 提供两款接受相同链接的 X 工具，分工值得一览：

解析器是分析师；生成器是建造者。一套发布流程完全可以先后用到两者——先分析以识别并规范化一条混乱链接的指向，再产生把它放上页面。两者在语法上天然一致——解析器认作推文的链接，就是生成器能嵌入的链接。

它不能做什么

边界在此列明，以免对工具过度信任：

• 不嵌入时间线、个人主页、清单、Spaces 或话题。 它们是拥有不同标记的其他 X 界面；oEmbed 端点的个人主页支持产出的是时间线锚点而非推文卡片，生成器会拒绝它们。若有需求，专门的工具才是诚实的载体。
• 不解析无用户名的链接。 /i/web/status/… 到达时缺少规范形式所要求的用户名，工具不会去猜。打开链接，拷贝完整 URL。
• 不解析 t.co 短链接。 光秃秃的短链接不携带推文身分；请粘贴目标地址。
• 不绕过隐私设置或删除状态。 受保护账号、已删帖子以及禁用了嵌入的作者，产出的代码正确却什么都渲染不出来。任何工具都改变不了这一点。
• 不在请求之前验证推文。 验证是语法层面的。推文是否存在只有端点的回应才能回答——不可用的推文表现为失败的请求。
• 不替 widget 做样式。 渲染后卡片内的颜色、字体和外观归 X 管。属于你的只有摆放位置（对齐、宽度）和内容取舍（对话、媒体）。
• 不替你安装代码。 你拷贝的就是你粘贴的；工具伸不进你的 CMS 或网页搭建器。

疑难排解

隐私与数据处理

这款工具对自己的流量很诚实：比零请求的兄弟工具多，但依然全程直连 X。

• 产生动作每次向 X 发送一次推文 URL。 按下产生或更改任何选项，都会恰好产生一次指向 publish.x.com/oembed 的 HTTPS GET，附带规范推文 URL 和你的选项。请求从你的浏览器直达 X 的基础设施——没有任何 Toollect 服务器代理、记录或看到它。
• 预览加载的是 X 自己的机器。 渲染卡片要从 platform.x.com 取 widgets.js，从 X 的分发基础设施取渲染后的 iframe，从其图片主机取媒体——与你拷贝的代码将在读者浏览器中产生的流量一模一样。
• Do Not Track 会传播。 打开该选项后，产生的代码携带 data-dnt="true"——X 官方文档定义的信号，用于把嵌入及其页面浏览排除在个人化推荐和个人化广告之外。
• 无账号、无保存、无统计。 工具在造访之间不保留任何状态；关闭标签页一切终止。
• 发布这段代码就意味着你的访客在与 X 通信。 这是嵌入的天性——值得明说。如果你需要一个严格脱机的 X 工作流，本站的 X（Twitter）链接解析器以零网络请求完成它的全部工作。

技术规格

细节：

• 端点——GET https://publish.x.com/oembed?url={canonical}，免密钥，JSON 回应，无文档记录的速率限制；参数 maxwidth、theme、lang、hide_thread、hide_media、align、dnt、omit_script
• 输入语法——主机 x.com / twitter.com，可选 www. / mobile. / m. 前缀；用户名 [A-Za-z0-9_]{1,15}；推文 ID 为 15–19 位数字；通信协定头、结尾斜线、查看变体（/photo/1、/video/1 等）及查找串皆容忍并丢弃
• 规范输出 URL——https://x.com/{username}/status/{id}
• 推文宽度契约——220–550 像素（含端点）（端点会压缩越界值；历史默认 325，工具默认 550）；视频宽度 560–1920 像素以客户端方式应用到 data-media-max-width，因为端点无法输出它
• 语言——可选「自动」或 34 种 X widget 区域设置；具体选择（含 en）皆写入 data-lang，仅「自动」省略
• 脚本管理——服务器的 script 标签被剥离；https://platform.x.com/widgets.js 每工作阶段加载一次，20 秒逾时；渲染看门狗每 500 毫秒询问 iframe 一次，最多 15 秒后报告
• 重请求策略——每次选项或分页变更都会发起新的 oEmbed 请求；进行中的相同请求由忙碌守卫合并
• 自架输出需要——script-src 与 frame-src 允许 https://platform.x.com（旧版片段另加 https://platform.twitter.com），img-src 允许 https://abs.twimg.com 与 https://pbs.twimg.com
• 浏览器支持——所有现代浏览器（剪贴板 API；widgets.js 本身要求的 ES5 运行环境）

功能特色

• 一键从任意推文 URL 产生官方 X（Twitter）嵌入代码 – 单一工具内含推文与视频两种模式
• 完整重现 X 自家发布器的选项 – 浅色/深色主题、自动＋34 种界面语言、精确宽度、对齐、隐藏对话、隐藏媒体
• 在粘贴代码之前查看由 X 官方 widgets.js 渲染的实时预览
• 精确控制宽度 – 推文支持 220–550 像素，视频透过 data-media-max-width 支持 560–1920 像素
• 尊重你的访客 – 内置 Do Not Track 开关，以及省略重复 widgets.js 标签的选项
• 免费的浏览器端生成器，X 的脚本被封锁时给出清晰诊断 – 无需 API 密钥，无需注册

常见问题