把 30 秒產品介紹塞進 GitHub README 的最後一哩

一個人做產品第 15 / 18 篇

本篇是「一個人做產品」系列的第 15 / 18 篇。你可以從系列總覽開始閱讀，也可以直接接著看本文。

GitHub README 影片內嵌：一件以為 5 分鐘卻做了 30 分鐘的事

剛幫自己的開源工具 TypeLate 做了 30 秒產品介紹影片，雙語版（英文 + 繁中），自己挺滿意。

下一步：塞進 GitHub README，讓訪客一打開頁面就看到產品在動。

<video> 標籤而已，能多複雜？

結果這篇就是我花了 30 分鐘踩三個雷之後，才發現 GitHub 有個沒明說的潛規則：README 的 <video> 只認他們自家 CDN，其他任何 URL 都不會 inline 播放。

如果你也想把產品 demo 塞進 README，這篇可以幫你省下我那 30 分鐘。

試法 1：相對路徑（直覺第一手）

我先試最直覺的：把 MP4 commit 進 repo，用相對路徑。

<video src="docs/promo.mp4" width="700" controls></video>

push 上去之後打開 README——player 渲染出來了，看起來很正常。

點 play。

⋯⋯沒反應。

「奇怪，是路徑問題嗎？」我用絕對的 raw URL 再試一次：

<video src="https://raw.githubusercontent.com/USER/REPO/main/docs/promo.mp4" controls></video>

一樣沒反應。

curl 一驗就明白了：

$ curl -sI -L "https://raw.githubusercontent.com/USER/REPO/main/docs/promo.mp4"
HTTP/2 200
content-type: application/octet-stream
content-disposition: attachment; filename=promo.mp4

Content-Disposition: attachment —— 瀏覽器把這個 URL 當「下載檔」，不會餵給 <video> 解碼器。<video> 標籤雖然在 HTML 結構裡存在，但 src 指向的資源根本不能 stream。

那 player 渲染出來只是個空殼。

試法 2：上傳到 GitHub Release（以為自家貨會放寬）

不死心。「Release asset 是 GitHub 正規 hosting，總該給正確 Content-Type 吧？」

用 gh CLI 上傳：

$ gh release upload v1.6.2 promo.mp4

URL 變成漂亮的 https://github.com/USER/REPO/releases/download/v1.6.2/promo.mp4。

再 curl ——

$ curl -sI -L "https://github.com/USER/REPO/releases/download/v1.6.2/promo.mp4"
HTTP/2 302
location: https://github-production-release-asset-...amazonaws.com/...
HTTP/2 200
content-type: application/octet-stream
content-disposition: attachment; filename=promo.mp4

還是 attachment、還是 octet-stream。

GitHub 不會因為你正式上架就放寬 Content-Type。Release asset 跟 raw 走的是同一條「強制下載」路線。

第二雷踩完，影片在 README 還是不會動。

試法 3：終於認清現實——drag-drop 是唯一路徑

抓著疑問翻 GitHub Docs 跟一堆 Stack Overflow 問答，才拼出真相：

GitHub Markdown 的 <video> 標籤只支援來自他們自家「user-attachments」CDN 的 URL，長這樣： https://github.com/user-attachments/assets/{UUID}

而這串 UUID 只能透過 github.com 的網頁編輯器（編輯 README、留言 PR、開 Issue 都可以），把 MP4 檔案直接「拖放」進文字框產生。GitHub 在背後偷偷上傳到自家 CDN，自動把 magic URL 插入 markdown。

沒有 API。沒有 CLI 指令。沒有任何純 script 路徑。

也就是說：

URL 類型	inline 播放？	自動化？
相對路徑（repo 內檔案）	❌	✅
raw.githubusercontent.com	❌（attachment）	✅
releases/download/…（剛剛試的）	❌（attachment）	✅
user-attachments/assets/{UUID}	✅ 串流播放	❌（web-only 拖放）

60 秒手動操作，但這是唯一通的路。

實際操作步驟（給跟我一樣踩過雷的你）

打開 https://github.com/USER/REPO/edit/main/README.md
把 MP4 檔從 Finder/Explorer 直接拖進編輯區的文字框
等個 5-10 秒，GitHub 把它上傳到自家 CDN
編輯區會自動插入 <video> 標籤，src 是 https://github.com/user-attachments/assets/{UUID}
點下方「Commit changes」按鈕，寫好 message 提交

完。從拖檔到完成，60 秒。

反思（一）這不是 bug，是設計

退一步想，GitHub 這樣設計其實合理。

如果他們允許任何 raw / release URL 都能 inline 串流，相當於每個 GitHub repo 都變成免費影片 CDN。隨便一個熱門開源專案的 README，每秒被千百人開啟，流量帳單會炸到爆。

把 inline video 鎖在他們能掌控的 user-attachments CDN，他們可以：

限制單檔大小（影片：免費方案 10MB、付費方案 100MB）
限制總流量
防止別人拿 GitHub 當免費影片 host 嵌到其他網站
統一統計播放數據

對追求「100% pure CLI flow」的工程師來說，這 60 秒手動操作是個刺。但站在平台方角度，是一個合理的取捨。

反思（二）早點接受「有些事就是要手點」

我真正花時間最多的，其實不是測試本身——curl 跑 header 比較其實只要 5 分鐘。

花最多時間的是不甘心：

試完 raw URL 失敗，「應該還有別的 URL 格式」
試完 release URL 失敗，「也許有什麼隱藏的 query string」
翻完 docs 沒答案，「不對啊一定有 API」

直到認清「沒有 API、沒有自動化路徑、就是要手動拖放一次」，我才能繼續往前。

這個心態陷阱不只發生在這次。每次我遇到「明明感覺應該能自動化但沒有現成方案」的場景，本能都是再多花 30 分鐘找解法，而不是花 60 秒手動做掉。

很多時候那 60 秒比 30 分鐘更划算。

如果一個一次性的手動操作只要 60 秒，就去做。如果這個操作會重複 100 次，再來想自動化。

對 indie hacker 來說，這個簡單的規則比「強迫症追求純 script」更能保護你的時間。

TL;DR

想把產品 demo 影片塞進 GitHub README？

別試 <video src="https://raw.githubusercontent.com/..."> —— 不會 stream
別浪費時間上傳到 Release 再引用 —— 同樣不會 stream
打開 github.com 的 README 編輯器 → 直接把 MP4 拖進文字框 → 用 GitHub 自動產生的 user-attachments/assets/{UUID} URL → 完成
保留你的 MP4 在 repo 裡（例如 docs/promo.mp4） —— 即使不能 inline 播放，commit history 和 download 連結仍有用

整段過程 60 秒。

別像我一樣花 30 分鐘才接受這件事 🥲

延伸閱讀

還沒被說服要花一天做 30 秒影片？ 從訊息密度、頂級 OSS 共識、ROI 三個角度說明為什麼值得： 👉 《為什麼一支 30 秒影片是 OSS 上架最大的槓桿》 — 給還在猶豫「值不值得」的人

還沒有一個夠 landing-page 感的 README？ 在塞 demo 影片之前，先把 README 的基本骨架排好： 👉 《GitHub README 排版術：把開源專案首頁變成 landing page》 — 6 個元素 + 章節順序模板，給第一次發 OSS 的人

想用其他方式呈現產品 demo？ <video> + user-attachments 只是 5 種策略之一。如果你的 demo 是 terminal CLI 場景、影片超過上限（免費方案 10MB / 付費方案 100MB）、要 100% 純 CLI flow，或想要 SEO 加分——還有另外 4 種替代方案各有取捨： 👉 《GitHub README 動態 demo 的 5 種策略：從 GIF 到自架 CDN》 — 有決策樹幫你選最適合的策略