GitHub README 動態 demo 的 5 種策略：從 GIF 到自架 CDN
先備知識：這篇假設你已經有一個排得不錯的 README 骨架（centered hero、badges、章節順序）。如果還沒，建議先讀 《GitHub README 排版術：把開源專案首頁變成 landing page》 補基礎。
在 GitHub README 呈現動態 demo，其實有 5 種策略
上一篇 《把 30 秒產品介紹塞進 GitHub README 的最後一哩》 結尾說：「user-attachments 是 GitHub <video> 唯一能 inline 播放的路。」
但那個結論有個前提：你想用 <video> 標籤 inline 播放。
如果放寬這個前提，會發現「在 GitHub README 呈現產品動態 demo」其實有 5 條截然不同的路，每條都有自己的取捨。
這篇我把它們整理成決策樹，給：
- 不想被 GitHub web UI 卡 60 秒的人
- README 要在 npm registry / VSCode preview 也能正常顯示的人
- demo 是 terminal 場景的人
- 影片超過 Free 方案 10MB 上限（付費方案 100MB）的人
策略 1：動畫 GIF（萬用無腦）
把 MP4 轉成 GIF，用 <img> 標籤嵌入。
# 一行流程：30 秒影片轉 720p、10fps GIF
ffmpeg -i input.mp4 -vf "fps=10,scale=720:-1:flags=lanczos" -loop 0 demo.gif
# 進階：用 gifski 壓得更小（brew install gifski）
ffmpeg -i input.mp4 -vf "fps=10,scale=720:-1" -f image2pipe -vcodec ppm - | \
gifski -o demo.gif --fps 10 -README 嵌入：
優點：
- ✅ 任何 markdown viewer 都顯示（GitHub、npm registry、VSCode preview、Reddit、Notion 全部）
- ✅ 完全自動化，純 CLI flow
- ✅ Auto-play，不用點
缺點：
- ❌ 檔案大：30 秒 720p GIF 通常 5-15MB
- ❌ 沒有音訊
- ❌ 畫質受 256 色限制，漸層/陰影會出現色帶
- ❌ 強制 loop 播放，讀者讀文字時持續干擾
適合： 短 demo（≤ 10 秒）、純視覺場景、最大相容性優先。
策略 2：GitHub user-attachments（上篇結論）
打開 github.com 編輯 README，把 MP4 直接「拖」進文字框。GitHub 上傳到自家 CDN 產生：
https://github.com/user-attachments/assets/{UUID}完整流程在上一篇講過，這裡只列取捨。
優點：
- ✅ 真正的
<video>播放器（含 scrubber、音訊、全螢幕、loop 控制） - ✅ 串流播放，不用整段下載
- ✅ GitHub 自家 CDN，全球節點快
缺點：
- ❌ 沒有 API，只能 web UI 拖放
- ❌ 單檔上限視方案而定：Free 10MB、Pro/Team/Enterprise 100MB
- ❌ 只在 github.com 顯示。npm registry、VSCode preview、Reddit 看到的是空白 / 損壞圖示
適合： 影片在上限內（Free ≤ 10MB / 付費 ≤ 100MB）、能接受 60 秒手動、主要受眾在 github.com。
策略 3：外部 CDN（Netlify Drop / Cloudflare R2）
自己 host MP4 到會正確回傳 Content-Type: video/mp4 的 CDN，README 用 <video src="https://..."> 直接引用。
最快上手的選項：
- Netlify Drop：把
public/資料夾拖到 app.netlify.com/drop，30 秒拿到 URL - Cloudflare R2：免費 10GB、0 出口流量費，要設定 bucket + 綁網域
- 已經有 GitHub Pages 或自架網站 → 直接放進
public/就好
驗證 Content-Type 正確（這是關鍵，CDN 設錯就不能 stream）：
$ curl -sI https://your-cdn.example.com/promo.mp4 | grep -iE "content-(type|disposition)"
content-type: video/mp4
# 沒有 content-disposition: attachment ← 這行不能出現README 嵌入：
<video src="https://your-cdn.example.com/promo.mp4"
poster="docs/poster.jpg"
width="700" controls></video>優點：
- ✅ 完全自動化（CI 推送就更新）
- ✅ 無檔案大小限制
- ⚠️ 平台相容性有限：在 GitHub Pages / 自架網站 / 支援 raw HTML 的 viewer 可正常播放；但 github.com README 不會顯示（GitHub sanitizer 會 strip 掉指向非 githubusercontent.com 的
<video>標籤）；npm registry / VSCode preview 不保證支援 - ✅ 真正的播放器 + 音訊（限支援 raw HTML 的環境）
缺點：
- ❌ 多一個服務要維護
- ❌ 流量爆掉要付錢（Netlify 自 2025-09 起新帳號改為 credit 制、免費 300 credits/月，舊制 legacy 帳號才是固定 100GB/月，實際額度以 Netlify 當前 pricing 為準；建議直接用 R2 的 10GB + 0 出口流量費較單純）
- ❌ 自訂網域可能要設 CORS 才能跨來源 stream
適合： 影片大、要 100% 自動化、有現成 CDN 可用，且目標是 GitHub Pages / 自架網站（而非 github.com README 本身）。
策略 4：YouTube / Vimeo 縮圖連結（SEO 加分）
GitHub 不會 render YouTube <iframe> embed（HTML sanitizer 把 iframe 整個 strip 掉），但可以放縮圖連結，點擊跳到 YouTube。
[](https://youtu.be/VIDEO_ID)YouTube 自動提供四種縮圖（直接拿，不用自己截）：
| 解析度 | URL |
|---|---|
| 1280×720 | https://img.youtube.com/vi/{ID}/maxresdefault.jpg |
| 640×480 | https://img.youtube.com/vi/{ID}/sddefault.jpg |
| 480×360 | https://img.youtube.com/vi/{ID}/hqdefault.jpg |
| 320×180 | https://img.youtube.com/vi/{ID}/mqdefault.jpg |
優點：
- ✅ SEO 加分：影片本身被 Google 索引
- ✅ 無流量成本（YouTube CDN 全球）
- ✅ 同支影片可重用：README + Twitter + Threads + 官網
- ✅ 有觀看數據可追蹤（YouTube Analytics）
缺點：
- ❌ 點擊跳走 README，使用者離開原頁
- ❌ 品牌綁定 YouTube（前後可能有廣告）
- ❌ 需要 Google 帳號 / YouTube channel
適合： 產品行銷導向、做完一支影片想多平台重用、在乎 SEO。
策略 5：Asciinema（terminal demo 專用）
不是影片，是 terminal 事件流的「重播」。錄製和播放都是純文字事件，檔案 KB 級別。
# 安裝
brew install asciinema
# 錄製（按 Ctrl+D 結束）
asciinema rec demo.cast
# 上傳到 asciinema.org（首次會要求登入）
asciinema upload demo.cast
# → 拿到 https://asciinema.org/a/XXXXXXREADME 嵌入（SVG 縮圖連到播放頁）：
[](https://asciinema.org/a/XXXXXX)優點：
- ✅ 檔案極小（30 秒錄製通常 5-20KB）
- ✅ 文字可以選取複製——讀者直接複製你 demo 裡的指令
- ✅ 純 SVG 縮圖在 README 完美顯示
- ✅ 可自架 player（不想依賴 asciinema.org 的話）
- ✅ 開源工具：asciinema / asciinema-player
缺點：
- ❌ 只能錄 terminal，無法錄 GUI demo
- ❌ 縮圖點擊跳走（跟 YouTube 策略類似）
適合： CLI 工具 demo、Shell 教學、DevOps 流程示範。
決策樹：你該選哪個
你的 demo 是 terminal CLI 場景？
├─ 是 → 策略 5：Asciinema
└─ 否
↓
影片超過方案上限（Free >10MB / 付費 >100MB）或 demo 超過 30 秒？
├─ 是 → 策略 3：外部 CDN
└─ 否
↓
音訊重要嗎？
├─ 是 → 策略 2（user-attachments）或 3（CDN）
└─ 否
↓
想要 100% 純 CLI flow，不能手動？
├─ 是 → 策略 1：GIF（最相容）或 3（CDN，最乾淨）
└─ 否
↓
想要 SEO 加分 + 多平台重用？
├─ 是 → 策略 4：YouTube 縮圖
└─ 否 → 策略 2：user-attachments（最省事）一張表看完所有取捨
| 策略 | 檔案大小 | 自動化 | 跨平台相容 | 音訊 | 適合場景 |
|---|---|---|---|---|---|
| 1. GIF | 大（5-15MB） | ✅ 純 CLI | ✅ 全部 | ❌ | 短 demo、最大相容 |
| 2. user-attachments | Free ≤10MB / 付費 ≤100MB | ❌ 60 秒手動 | ⚠️ 只 github.com | ✅ | 影片在上限內、主要在 GitHub |
| 3. 外部 CDN | 不限 | ✅ 全自動 | ⚠️ github.com 不顯示 | ✅ | 大檔案、GitHub Pages/自架網站 |
| 4. YouTube 縮圖 | 0（外部） | ✅ 上傳一次 | ✅ 全部 | ✅ | 想 SEO + 多平台重用 |
| 5. Asciinema | 極小（KB） | ✅ 純 CLI | ✅ 全部 | ❌ | terminal demo 專用 |
我自己的選擇（實戰案例）
完整踩雷紀錄在 《把 30 秒產品介紹塞進 GitHub README 的最後一哩》——我做 TypeLate 這次選了策略 2（user-attachments），原因很簡單：
- 影片只有 2MB，遠低於 Free 方案 10MB 上限
- 主受眾就在 github.com（README 就是首頁）
- 60 秒手動可以接受（一支影片只上一次）
但如果未來：
- 影片變長到 30MB → 改策略 3（Cloudflare R2 host）
- 想推到 Product Hunt → 加策略 4（YouTube）多平台
- 變成純 CLI 工具 → 策略 5（Asciinema）取代
5 種策略不是互斥的，可以混用。例如：策略 2 給 GitHub 訪客真播放器，同時策略 4 給 YouTube SEO，策略 1 給 npm registry 看到 GIF——一支影片打三個通路。
TL;DR
GitHub README 的動態 demo 不只 <video> 一條路：
- GIF：相容性王者，但檔案大、無音訊
- user-attachments：真播放器，但上限視方案（Free 10MB / 付費 100MB）+ 60 秒手動
- 外部 CDN：100% 自動化、無限制，但要多維護一個服務
- YouTube 縮圖：SEO 加分，但點擊跳走 README
- Asciinema：terminal 專用，KB 級別，文字可複製
選哪個看你的 demo 內容、自動化需求、跨平台需求三軸權衡。
至於為什麼值得花力氣做這支 demo 影片，可參考 《為什麼一支 30 秒影片是 OSS 上架最大的槓桿》。
