Markdown 嵌入影片

寫技術文件或者做專案展示的時候，經常需要嵌入一段影片——比如產品功能錄屏、教學影片、會議錄影。Markdown 本身沒有影片語法，不像 Markdown 圖片 有 ![]() 這麼方便。但好在 Markdown 支援內聯 HTML，用 iframe 就能把影片嵌進去。今天就把各種嵌入方式、各平臺的相容情況、以及不支援的時候怎麼辦，一次講清楚。

為什麼 Markdown 沒有原生的影片語法

先說一個事實：標準 Markdown 和 CommonMark 規範裡都沒有定義影片嵌入語法 。Markdown 最初設計的目標是「易讀易寫的純文字格式」，影片嵌入超出了這個範圍。所以不管你想 embed YouTube 影片、Vimeo 影片，還是本地影片檔案，都得藉助 HTML。

具體來說有這幾種思路：

  1. HTML <iframe> 標籤：嵌入線上影片平臺（YouTube、Vimeo、Bilibili）
  2. Markdown 圖片連結：用影片縮圖做「假嵌入」，點擊跳轉到影片頁面
  3. HTML5 <video> 標籤：嵌入本地影片檔案
  4. 平臺特定擴展語法：少數編輯器或外掛支援的自訂語法

下面一個一個來。

用 iframe 嵌入 YouTube 影片

YouTube 是最常見的影片嵌入需求。關鍵是拿到影片的 embed URL——它和普通觀看地址不同，用的是 youtube.com/embed/ 路徑：

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen>
</iframe>

其中 dQw4w9WgXcQ 是影片 ID，就是 YouTube 影片連結 watch?v= 後面的那串字元。

怎麼獲取影片 ID

YouTube 影片連結一般長這樣：https://www.youtube.com/watch?v=dQw4w9WgXcQ，v= 後面的值就是影片 ID。把它拼到 https://www.youtube.com/embed/ 後面就行。

如果連結是短連結格式 https://youtu.be/dQw4w9WgXcQ，最後那段也是影片 ID。

iframe 各屬性解釋

說實話，直接複製上面的程式碼改個影片 ID 就夠用了。但瞭解一下各屬性的含義有好處：

屬性作用
width / height播放器的寬度和高度，單位畫素
src影片的嵌入地址，必須是 /embed/ 格式
title無障礙標題，熒幕閱讀器會用它來描述 iframe 內容
frameborder="0"去掉 iframe 的邊框（HTML5 中已廢棄，但很多範例還保留）
allow控制影片可以使用的瀏覽器功能（自動播放、剪貼簿等）
allowfullscreen允許使用者點擊全熒幕按鈕

allow 屬性裡的內容是 YouTube 建議的安全許可權列表，直接照抄就好。如果你不介意少幾個功能，只保留 allowfullscreen 也能正常播放。

用 iframe 嵌入 Vimeo 影片

Vimeo 的嵌入方式和 YouTube 幾乎一樣，只是 embed URL 不同：

<iframe width="640" height="360"
  src="https://player.vimeo.com/video/19706846"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen>
</iframe>

Vimeo 的影片 ID 就是連結最後的數字，比如 https://vimeo.com/19706846 裡的 19706846。注意 Vimeo 的播放器域名是 player.vimeo.com，不是 www.vimeo.com。

順便提一句，Vimeo 的嵌入地址格式和普通觀看地址完全不同。如果你直接拿 https://vimeo.com/19706846 塞進 iframe 的 src 裡，是不會有播放器的——必須用 player.vimeo.com/video/ 這個路徑。

用 iframe 嵌入 Bilibili 影片

對於中文使用者來說，B 站（Bilibili）可能是更常用的影片平臺。嵌入 B 站影片也用 iframe：

<iframe width="640" height="360"
  src="//player.bilibili.com/player.html?bvid=BV1xx411c7mD&page=1"
  frameborder="0"
  allowfullscreen>
</iframe>

B 站的嵌入地址需要用 BV 號（BV1xx411c7mD），就是影片連結裡的那串 ID。page=1 表示第一P（分P影片的話可以改成對應頁數）。

BV 號在影片連結裡就能找到，比如 https://www.bilibili.com/video/BV1xx411c7mD 中 BV 開頭的那串就是。

縮圖連結方案：全平臺通用的替代方案

上面說的 iframe 方案有一個大問題：很多平臺會過濾掉 iframe 標籤。最典型的就是 GitHub——它的 HTML 白名單裡不包含 iframe [^3]。你在 GitHub README 裡寫 iframe，推上去一看，什麼都沒有。

這時候最靠譜的替代方案是用 Markdown 的圖片+連結語法，做一個「看起來像影片」的縮圖：

[![影片標題](https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg)](https://www.youtube.com/watch?v=dQw4w9WgXcQ)

這行程式碼做了一件事：顯示 YouTube 影片的縮圖，點擊後跳轉到影片頁面。它用的是純 Markdown 語法（Markdown 連結 + Markdown 圖片），所以在所有平臺都能正常顯示 。

YouTube 的縮圖 URL 是有規律的，不需要手動截圖：

縮圖URL 格式解析度
預設https://img.youtube.com/vi/VIDEO_ID/default.jpg120×90
中等https://img.youtube.com/vi/VIDEO_ID/mqdefault.jpg320×180
高清https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg480×360
最高清https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg1280×720

一般用 hqdefault.jpg 就夠了，清晰度不錯，載入也快。

加個播放按鈕

縮圖看起來畢竟不像影片播放器。一個常用的技巧是在縮圖上疊加一個播放按鈕圖示——不過這需要 CSS 或 SVG，在純 Markdown 裡做不到。最簡單的方式是讓縮圖本身帶播放按鈕，YouTube 的 hqdefault.jpg 預設就有中間那個黑色半透明條。

我之前在一個開源專案的 README 裡用這個方法放了一個功能演示影片。雖然點擊後跳轉到 YouTube 而不是直接播放，但至少使用者能看到影片封面，知道這裡有個影片可以看。比單獨放一個文字連結好多了——文字連結你根本不會注意到它是影片。

HTML5 video 標籤：嵌入本地影片

如果你有一個本地的 .mp4 影片檔案想嵌入（比如放在同一倉庫裡的演示錄屏），可以用 HTML5 的 <video> 標籤：

<video width="640" height="360" controls>
  <source src="demo.mp4" type="video/mp4">
  你的瀏覽器不支援 video 標籤
</video>

controls 屬性會顯示播放控制條（播放/暫停、進度條、音量）。src 可以是相對路徑或絕對 URL。

不過說實話，這種方式限制很大。GitHub 會過濾 <video> 標籤，很多線上 Markdown 編輯器也不支援。它更適合用在 Jekyll、Hugo 這類自己控制的靜態站點裡。

響應式影片嵌入

固定寬高的 iframe 在手機上會很難看——要麼溢出熒幕，要麼擠成一團。如果你在自己搭的網站（Jekyll、Hugo 等）裡用 Markdown，可以用 CSS 做響應式適配：

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
    src="https://www.youtube.com/embed/dQw4w9WgXcQ"
    frameborder="0"
    allowfullscreen>
  </iframe>
</div>

這裡 padding-bottom: 56.25% 是 16:9 寬高比的百分比表示（9÷16 = 0.5625）。iframe 用絕對定位鋪滿容器，不管熒幕多寬，影片播放器始終維持 16:9 比例。

如果你用現代瀏覽器，還有更簡潔的寫法：

<div style="aspect-ratio: 16/9; width: 100%;">
  <iframe style="width: 100%; height: 100%;"
    src="https://www.youtube.com/embed/dQw4w9WgXcQ"
    allowfullscreen>
  </iframe>
</div>

aspect-ratio 是 CSS 的新屬性，主流瀏覽器都支援了，寫起來簡潔很多。不過 GitHub 會過濾 inline style，所以這個方案只適用於你自己的網站。

我之前給一個 Jekyll 部落格加影片的時候就踩了坑——直接用 width="560" height="315" 的固定尺寸，結果手機上看影片直接撐出了熒幕，得橫向捲動才能看完。後來換成 aspect-ratio 方案，手機和桌面都能正常顯示。

平臺特定擴展語法

少數平臺提供了自訂的 video embed 語法，但這些語法只在特定環境裡有效：

markdown-it-video 外掛

@[youtube](dQw4w9WgXcQ)
@[vimeo](19706846)

這個語法由 markdown-it-video 外掛提供，使用 markdown-it 作為解析器的專案（比如用 Node.js 搭建的站點）可以裝這個外掛來支援 [^4]。

October CMS

!![560x315](https://www.youtube.com/embed/5xK8RK54IAc)

October CMS 的 Markdown 解析器支援這個特殊語法，它會被轉換為標準的 iframe 嵌入。

這些自訂語法都不通用，換個平臺就失效了。除非你確定只在特定環境裡用，否則還是老老實實寫 iframe 更靠譜。

各平臺相容性對比

不同平臺對影片嵌入的支援差異很大，這裡整理了主流平臺的情況：

平臺<iframe><video>縮圖連結備註
Jekyll / Hugo✅✅✅自己控制的站點，HTML 完全保留
Obsidian✅✅✅本地預覽支援 iframe
Typora✅✅✅編輯器內直接播放
VS Code 預覽⚠️❌✅iframe 部分支援，受安全策略限制
GitLab✅❌✅GLFM 支援 iframe [^3]
GitHub❌❌✅HTML 白名單不含 iframe [^3]
Notion❌❌❌用 /embed 命令嵌入
Stack Overflow❌❌⚠️圖片可顯示，但嵌入影片不友好

幾個關鍵點：

  • GitHub 是限制最嚴的平臺，iframe 和 video 都不支援，只能用縮圖連結方案 [^3]
  • GitLab 反而支援 iframe，如果你用 GitLab 管理文件，可以直接嵌入影片
  • Obsidian 和 Typora 對影片嵌入最友好，iframe 和 video 標籤都能正常工作
  • Notion 有自己的嵌入方式，用 /embed 命令貼上影片連結就行，不需要寫程式碼

實際使用場景

專案 README 裡放演示影片

## 功能演示

點擊查看錄屏演示：

[![功能演示影片](https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg)](https://www.youtube.com/watch?v=dQw4w9WgXcQ)

GitHub 上最常見的方式。雖然不是真正的嵌入式播放，但至少能看到影片封面。

技術部落格嵌入教學影片

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="教學影片"
  allowfullscreen>
</iframe>

Jekyll、Hugo 等部落格系統裡可以直接用 iframe，讀者不用離開頁面就能看影片。

Obsidian 筆記裡嵌入會議錄影

## 2024-03-15 產品評審會議

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  allowfullscreen>
</iframe>

在 Obsidian 裡做會議筆記時，把錄影直接嵌在筆記裡，回顧的時候不用再翻聊天記錄找影片連結。

常見問題

GitHub README 裡怎麼嵌入影片？

GitHub 不支援 <iframe> 和 <video> 標籤。唯一的辦法是用縮圖連結：

[![演示影片](https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)

這不是真正的影片嵌入，而是顯示影片縮圖，點擊後跳轉到 YouTube 播放 [^3]。

Markdown 有影片語法嗎？

沒有。標準 Markdown 和 CommonMark 規範都不包含影片嵌入語法 。所有影片嵌入都需要藉助 HTML 標籤（iframe 或 video）。

為什麼我的 iframe 不顯示？

最常見的原因有兩個：

  1. 平臺過濾了 iframe：GitHub、部分線上編輯器會出於安全考慮，把 iframe 標籤整個刪掉。檢查一下你的目標平臺是否在白名單裡支援 iframe。
  2. embed URL 格式不對：YouTube 的 iframe src 必須是 youtube.com/embed/VIDEO_ID，而不是 youtube.com/watch?v=VIDEO_ID。Vimeo 的必須是 player.vimeo.com/video/ID。用錯了地址 iframe 會顯示空白或報錯。

如何讓嵌入的影片自適應熒幕寬度？

用 CSS 的 aspect-ratio 屬性包裹 iframe：

<div style="aspect-ratio: 16/9; width: 100%;">
  <iframe style="width: 100%; height: 100%;"
    src="https://www.youtube.com/embed/VIDEO_ID"
    allowfullscreen>
  </iframe>
</div>

這個方案需要目標平臺支援 inline style（GitHub 不支援）。

Bilibili 影片怎麼獲取嵌入程式碼？

在 B 站影片頁面點擊「分享」按鈕，選擇「嵌入程式碼」即可獲得完整的 iframe 程式碼。或者手動拼接：//player.bilibili.com/player.html?bvid=你的BV號。

參考來源

: Markdown Guide — Extended Syntax: MDN Web Docs — iframe 元素[^3]: GitHub Docs — 在 Markdown 中撰寫運算式[^4]: GitHub — markdown-it-video 外掛