GitHub README 其實會跑動畫——但 LottieFiles 沒告訴你的三個坑

LottieFiles 在 5 月 21 日丟了一個鉤子：「大多數開發者不知道 GitHub README 會跑動畫。」這則貼文 24 小時內衝到 69 萬次觀看、近 1000 個分享。

這句話對一半。GitHub README 確實會跑動畫，但不是 LottieFiles 想讓你聯想到的那種。他們的 Lottie JSON 直接貼進 README，會被當成一個壞掉的連結。真正能動的只有兩條路——而且每一條都有它自己的雷。

這篇拆三件事：①GitHub 實際支援什麼、②Lottie 動畫要怎麼真的塞進 README、③底下留言區網友丟了哪些 demo repo（順便看 LottieFiles 自家是怎麼做的）。

先示範一個：這就是 Lottie 動畫

下面這個動畫不是 GIF，是 LottieFiles 的 .lottie 檔案，透過 dotlottie-wc web component 在你瀏覽器即時跑 Skottie/Thorvg runtime 解碼。檔案只有幾 KB，可以無限放大不糊。

問題來了：這段 web component 在這篇 blog 跑得起來，是因為我有 JavaScript runtime。GitHub README 沒有，所以同一個 .lottie 檔案貼到 GitHub 上會變成壞連結。

這就是 LottieFiles 那則貼文的「潛規則」——他們的動畫格式本身進不了 README，得先轉檔。

GitHub 在 README 裡到底會渲染什麼

GitHub Flavored Markdown 對動畫類資源的支援，實際只認三種：

1. 動畫 GIF：放在 repo 裡或外部圖床都行，<img src="...gif" /> 直接動。
2. CSS 動畫 SVG：SVG 檔案內嵌 <style> 區塊、用 @keyframes + transform 跑動畫，會動。
3. APNG：技術上可以，但實務上幾乎沒人用。

至於 LottieFiles 本身的 JSON 格式——.lottie 或 .json——GitHub README 完全不會渲染。它不是圖片，markdown 的 <img> 標籤也接不上。你得先把它轉成 GIF（LottieFiles 自己提供 Lottie to GIF 工具）或轉成 dotLottie web 元件嵌進網頁，但 web 元件需要 JavaScript runtime，README 裡也跑不起來。

說白了，LottieFiles 那則貼文的潛台詞是「讓我們把你的 Lottie 動畫變成 GIF」，而不是「Lottie 直接能跑」。

SVG 動畫的隱形地雷：<animate> 標籤一律被吃掉

這是第二個坑，也是最多人踩的。

Stack Overflow 上有一則經典提問：作者用 termtosvg（Python 工具）錄了終端機 session 輸出成 SVG，放進 README 變成黑屏；換成 svg-term-cli（同樣功能、Node.js 寫的）就會動。為什麼？

答案是：GitHub 把 SVG 裡的 <animate>、<animateTransform> 這類 SMIL 動畫標籤當成 script 處理，直接清掉。termtosvg 預設輸出 SMIL，所以 GitHub 拿到的是一個被剝光動畫指令的空殼 SVG。

svg-term-cli 不一樣，它用 CSS @keyframes 跑動畫，動畫描述全部寫在 SVG 內嵌的 <style> 區塊裡。CSS 不會被當 script 過濾，於是動畫能跑。

這條規則的實作建議：

• 動畫邏輯全部寫成 CSS，放在 SVG 檔案內的 <style> 區塊
• 不要用 <animate> 標籤（即使單元測試本機看起來好好的）
• 不要在 SVG 裡 <script>、<embed>、<iframe>、<foreignObject> 內嵌 HTML——GitHub 全部會 sanitize 掉互動行為
• 想被 :hover 觸發的動畫也不行，因為 GitHub 用 <img> 標籤載入 SVG，這種模式下 SVG 拿不到使用者輸入

GitHub Community 上 2025 年的一篇 Discussion #151372 直接問了「為什麼不放開 SVG 嵌入？」，官方至今沒回。CSS-only 是現實，不是建議。

實際翻 LottieFiles 自家 repo：他們怎麼做動畫的

LottieFiles 那則貼文底下，他們自己 follow-up 推了 4 個 repo 說「看我們的動畫」。我把每個翻過一輪，發現一個有趣的事實：

他們自家 README 全部都用 animated SVG，不是 GIF、也不是 .lottie 檔。

下面這四張就是 LottieFiles 4 個官方 repo README 第一屏直接抓過來的動畫。GitHub 在那邊看到什麼，你在這裡就看到什麼——它們在你瀏覽器裡會動，因為都是內嵌 CSS animation 的 SVG：

換句話說，LottieFiles 自己也知道 .lottie 檔案在 GitHub README 跑不起來。他們在 lottie.host 這個 CDN 把 Lottie animation 匯出成 SVG（內嵌 CSS 動畫），再用 <img> 標籤貼進 README。GitHub 看到的不是 Lottie，是一張會動的 SVG 圖。

thorvg 走的是不同路線——它是自己的 vector graphics engine 作者，所以動畫 SVG 是手寫的、commit 到 thorvg.site 這個附屬 repo 裡。不靠 lottie.host CDN，但本質一樣：CSS 動畫 SVG。

這個細節印證了上面那段論點——但 LottieFiles 在那則貼文裡完全沒講。他們只說 GitHub 能跑動畫，沒說那條路是 SVG export，不是 Lottie 原生。

三個來自 LottieFiles 官方圖庫的動畫範例

下面三個是 LottieFiles 官方公開圖庫挑出來的常用情境，跟典型 README 用途對齊：loading state、hero banner、CTA。每個都是 .lottie 檔案（< 10KB）即時 runtime 渲染，不是 GIF：

這些動畫在本文這頁能跑，是因為 blog 有 JavaScript runtime 載入 dotlottie-wc。要把同一個動畫貼到 GitHub README，你得：

1. 進去 LottieFiles 站，按 Download → Optimized GIF（或用 Lottie to GIF 工具），把它轉成 GIF
2. 或：用 LottieFiles 的 lottie.host 服務，匯出成 animated SVG，再用 <img> 標籤貼進 README
3. 不要：把 .lottie 或 .json 直接 commit 到 repo 然後寫 ![](animation.lottie)——markdown 不認

給 AI 用的提示詞：直接產出 README 動畫 SVG

不想找現成 Lottie 動畫、也不想自己畫？把下面這段提示詞貼給 Claude / ChatGPT / Gemini，改幾個變數，它會吐一份可以直接 commit 進 repo 的 animated SVG。重點是要把 GitHub 的限制寫進 prompt，不然 AI 預設會用 SMIL <animate> 標籤，貼上去整張變黑。

提示詞模板 A：通用 README hero animation

你是 SVG 動畫專家。請幫我產一個放在 GitHub README 第一屏的 animated SVG，主題是「{你的專案主題，例如：a CLI tool for parsing log files}」，視覺風格「{minimal / cyberpunk / playful / corporate}」，主色「{#6366F1 / 你的品牌色}」。

硬性限制（GitHub README 規定，違反整個動畫會變黑屏）：
1. 只能用 CSS animation（@keyframes + transform / opacity / fill），不能用 <animate>、<animateTransform>、<animateMotion> 這類 SMIL 標籤
2. 所有 <style> 區塊放在 SVG 內部，不能外部引用 CSS
3. 不能用 <script>、<iframe>、<foreignObject> 內嵌 HTML，這些會被 GitHub sanitize 掉
4. 不能依賴 :hover 或任何使用者輸入（GitHub 用 <img> 載入 SVG，互動事件接不到）
5. SVG 尺寸建議 1200×400 或 800×300，viewBox 一定要寫
6. 檔案盡量壓在 30KB 內

請直接輸出完整 SVG 程式碼，包含 <?xml version="1.0"?> 開頭，可以複製貼上直接存成 hero.svg。動畫要 loop infinite，速度 4-8 秒一個循環。

提示詞模板 B：把終端機 demo 轉成動畫 SVG

我有一段終端機 session，內容是：

```
$ {第一行指令}
{輸出第 1 行}
{輸出第 2 行}
$ {第二行指令}
{輸出 1}
{輸出 2}
```

請把它做成 animated SVG，模擬打字效果（每個字逐字出現），完整跑完一輪約 8 秒，最後停 2 秒再 loop。

硬性限制：
- 只能用 CSS @keyframes（typing effect 用 width transition + steps()）
- 不能用 <animate> 標籤
- 字體用 monospace，背景深色 (#1e1e2e)，前景淺色 (#cdd6f4)
- 不要 :hover 觸發
- viewBox 設 800×400

直接輸出完整 SVG。

提示詞模板 C：產出 light / dark mode 兩張對應的 SVG

請幫我產兩個檔案：hero-light.svg 和 hero-dark.svg。

主題：{你的專案描述}
風格：{minimal / 你的偏好}

light 版：白底 (#ffffff)，深色前景 (#0f172a)，accent 用 indigo (#6366F1)
dark 版：深色底 (#0a0a14)，淺色前景 (#f5f5f5)，accent 維持 indigo (#6366F1)

兩個 SVG 的動畫**一模一樣**——只有顏色不同，這樣它們在 GitHub 切換 theme 時不會跳。

CSS animation only，不要 SMIL <animate> 標籤。viewBox 1200×400。直接輸出兩份完整 SVG。

產出來之後，commit 到 repo 的 assets/ 目錄，然後在 README 寫：

<img src="assets/hero-light.svg#gh-light-mode-only" alt="專案 hero animation" />
<img src="assets/hero-dark.svg#gh-dark-mode-only" alt="專案 hero animation" />

GitHub 會根據使用者當下的主題自動切換對的那一張。整套流程不需要 JavaScript、不需要 build pipeline、不需要 LottieFiles 帳號——AI 寫 SVG、git commit、上線。

AI 輸出時最常見的兩個錯誤

跑這些提示詞時，AI 偶爾會犯這兩個錯，自己檢查一下再 commit：

1. 偷偷塞了 <animate> 標籤：哪怕你寫了「不能用」，有些模型還是會用，因為訓練資料裡 SMIL 範例太多。產出後在檔案裡 grep 一下 <animate、<animateTransform、<animateMotion，有就要求 AI 全部改成 CSS。
2. font 用外部 Google Fonts：例如 <style>@import url('https://fonts.googleapis.com/...');</style>，GitHub 不會載入外部資源，文字會掉回系統預設字型。要求 AI 改用通用 fallback：font-family: -apple-system, system-ui, sans-serif。

把這兩條加進你的 prompt 結尾當 checklist：「最後檢查：不能含 <animate*> 標籤、不能 @import 外部字型。」

進階：Scalar 的 README 是怎麼弄出來的

如果你要超越「動一動的 banner」，看看 Scalar 那篇 2025 年 5 月的文章——他們的 README 做了三件事：

1. light / dark mode 切換：用 #gh-light-mode-only 和 #gh-dark-mode-only 這兩個錨點，讓同一個 <img> 在不同主題下顯示不同 SVG。
2. ASCII art：因為 markdown 不會好好渲染 ASCII，他們把 ASCII 包進 SVG 的 <foreignObject> 裡再顯示出來。
3. 動態貢獻者牆：每個貢獻者的頭像用 SVG 嵌進來，整個 README 看起來像活的。

第一條其實是最容易抄的小技巧。你只要準備兩個 SVG 檔案，分別在 README 寫：

<img src="hero-light.svg#gh-light-mode-only" />
<img src="hero-dark.svg#gh-dark-mode-only" />

不需要 JavaScript、不需要 build pipeline，GitHub 會根據使用者當下的主題自動秀對的那一張。

該用哪一個：GIF vs CSS-SVG vs Lottie 轉檔

實務上挑哪一個，看你的素材來源：

• 既有 Lottie 動畫（從 LottieFiles 下載的）：在 LottieFiles 站上用 Lottie to GIF 工具轉成 GIF，這是 LottieFiles 那則貼文的真正用法。Lottie 原始 JSON 進不了 README。
• 終端機錄影：用 svg-term-cli（不要用 termtosvg），輸出 CSS 動畫 SVG。
• UI demo 影片：錄成短 GIF，控制在 5 秒、5MB 內，否則手機載入會卡。
• 資料視覺化、loading 動畫、icon：手寫或從 Illustrator 匯出 SVG，再把 CSS animation 內嵌到檔案裡——這條路最輕、最清晰。

如果你常常做這類 SVG 動畫和終端機錄製，鍵盤手感和外接螢幕的差別會直接反映在你願不願意 commit 一次又一次的微調——可以參考 蝦皮開發者裝備合集，挑套順手的工作環境再來折騰 README。

LottieFiles 那則貼文其實是聰明的內容行銷：用「你不知道吧」的鉤子，把流量導向他們的 Lottie-to-GIF 工具。技術上沒講錯，只是把「README 能動」跟「Lottie 能動」之間的轉換步驟刻意省略了。

知道了這層，你就不會去研究怎麼把 .lottie 檔案塞進 markdown——那條路根本不存在。

一句話收尾

GitHub README 不是不能動，是只認 CSS 動畫和 GIF。把這條規則記住，你的 repo 首頁可以不靠任何外部服務就跑起來；忘了它，你會花一個下午試圖把 Lottie JSON 嵌進 markdown。