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 金鑰，無需註冊

常見問題