前言

Mermaid 是「圖表即程式碼」（Diagram as Code）常見的工具，GitHub 上累積超過 85,000 顆星，使用者眾多。這一兩年它多了一個新身分：開發者跟 AI 協作時，用來描述系統架構與流程的共同語言。

不過寫過 Mermaid 的人大概都遇過兩個狀況：預設樣式在深色模式下不太好讀，以及想拿到一張能用的 PNG，往往得把程式碼複製到外部網站去轉，解析度也容易糊掉。

2026 年 5 月，VS Code 1.121 已經把 Mermaid 渲染內建到 Markdown 預覽，基礎渲染算是標配了。但美化與匯出這一段還是空白，這也是我開發 Super Mermaid 的起點。

為什麼 Mermaid 是最適合人與 AI 協作的圖表工具

先講結論：在所有畫圖的工具裡，Mermaid 大概是唯一一個「人跟 AI 都用原生格式看同一份東西」的。這句話聽起來很小，實際用起來差很多。

同一份東西，人看到圖，AI 看到字

Draw.io、Figma、Visio 畫出來的是圖檔。要拿給 AI 看，只能截圖丟進去，它得先認圖，認完也只能用講的告訴你哪裡怪，改不了。

Mermaid 剛好反過來：它本體就是幾行純文字，渲染之後才變成圖。你看到的是圖，AI 讀到的是文字，但兩邊指的是同一份原始碼。中間不需要翻譯，也不會有「你講的那張圖」跟「我看到的那張圖」對不起來的問題。

省 token 這件事，比想像中有感

token 可以想成 AI 的閱讀量：它一次能讀進去多少東西有上限，讀了多少也直接反映在帳單上。

同一份系統架構，用純文字一句一句描述「使用者按下結帳之後，前端呼叫訂單 API，訂單 API 再去問庫存服務，庫存不足就發補貨通知……」，大概要 2,000 個 token 上下；同樣的資訊寫成 Mermaid，400 到 500 個 token 就講完了，差不多省下 3 到 6 倍：

1-使用者在購物車頁按下結帳之後，前端會先呼叫訂單服務，
2-訂單服務要先向庫存服務確認這批商品的庫存是否足夠。
3-如果庫存足夠，就建立一筆訂單，接著呼叫金流 API 進行扣款；
4-如果庫存不足，就不建立訂單，改為發送補貨通知給採購。
5-金流扣款完成後，若付款成功，訂單狀態改為成立，
6-並通知倉庫出貨；若付款失敗，則要把先前預扣的庫存釋放回去。
7-（以上還只是主要流程，各種例外分支要再往下寫好幾段） 

1+flowchart LR
2+  A([使用者下單]) --> B[購物車結帳]
3+  B --> C{庫存足夠?}
4+  C -- 是 --> D[建立訂單] --> F[呼叫金流 API]
5+  C -- 否 --> E[發送補貨通知]
6+  F --> G{付款成功?}
7+  G -- 是 --> H[訂單成立] --> J([通知出貨])
8+  G -- 否 --> I[釋放庫存]

省下來的額度不會憑空消失，它會變成 AI 拿去多讀你幾支程式碼的空間。在動輒要餵十幾個檔案的對話裡，這個差距會一路累積。

AI 改得動，不必重新畫一次

架構調整的時候，如果圖是截圖或 .drawio 檔，只能請人重開工具重畫。Mermaid 只要改一行 A --> B，圖就跟著變，而這件事 AI 自己就能做完。

這也是為什麼跟 AI 討論架構時用 Mermaid 會比較順：你請它「把快取那層拆出來」，它回你的不是一段解釋，而是一份可以直接貼回檔案的新圖。

圖表跟程式碼一起進版控

因為是純文字，Mermaid 圖表可以跟程式碼放進同一個 commit，diff 一看就知道這次架構動了哪裡。文件圖表最常見的死法是跟現實脫節，放進 repo、讓 AI 改 code 時順手改圖，至少能把這一天往後推很久。

VS Code 內建 Mermaid 之後，還缺的兩件事

一、預設樣式與閱讀性

VS Code 內建渲染沿用 Mermaid 預設主題，在深色模式下「淺灰配白底」的線條與文字不太容易辨識。Cursor 論壇上有開發者分享，在比較多人的工程會議裡展示 Mermaid 圖表時，因為對比度偏低而不太好讀。GitHub Discussions、Obsidian 論壇也有不少「深色模式下難以閱讀」的回報。

Mermaid 官方在 v11.14.0 新增了 look: handDrawn（基於 rough.js）與 Neo 風格，但需要手動在每張圖表加上 %%{init}%% 設定區塊，門檻不算低，文件裡圖表一多就變成重複工作。

二、匯出流程

想要一張 PNG，多數工具的做法是：複製程式碼 → 開瀏覽器 → 貼到 mermaid.live → 下載圖片。這個流程會打斷在 VS Code 裡的節奏，而且匯出的預設解析度只有 1x，放進簡報或技術文件容易偏糊。簡報場景一般建議至少用 4x（約 384 DPI）渲染。

市場現況

現有方案多半是功能受限，或沒辦法直接整合進 VS Code 的工作流程。

Super Mermaid 的做法：自動上色與一鍵高解析匯出

自動套用高對比主題

不需手動設定，Super Mermaid 會自動為圖表套上高對比、依 subgraph 與節點類型上色的 Colorful 主題，深色或淺色模式下都比預設好讀一些。同樣一張「訂單處理流程」圖，套用後結構會比較清楚：

自動上色不只適用於流程圖，循序圖、ER 圖、甘特圖、心智圖、圓餅圖等也都會套上配色：

如果偏好白板手繪的風格，在工具列切換主題就能套用 Sketch 手繪風，適合教學或腦力激盪：

一鍵高解析匯出，不離開 VS Code

預覽介面直接提供 Export as PNG 和 Export as SVG 按鈕，可以一鍵產生 4x 高解析度（約 384 DPI）、透明背景的圖片，放進簡報或技術文件比較夠用。過程不需要切換視窗，也不用另外開瀏覽器。

給常用者的幾個功能

• Export All：一份 Markdown 文件裡有十幾張 Mermaid 圖時，可以一次匯出，不用逐張處理
• 簡報模式：直接在 VS Code 裡全螢幕展示圖表，會議時比較方便
• 圖表搜尋：文件一長、圖表一多時，快速定位到要看的那張
• 分享連結：產生可分享的連結，讓沒裝擴充套件的同事也能看圖

開發過程：和 Claude Fable 5 一起做這個擴充套件

這次開發我用了 Claude Fable 5，Anthropic 的第五代模型，定位在比較長時間的自主編碼任務，2026 年 6 月已在 GitHub Copilot 上開放使用。以下記錄幾個過程中的環節。

從目標到實作

我把核心目標描述給 Fable 5：「做一個 VS Code 擴充套件，攔截並美化 Mermaid 渲染，並提供高解析度圖片匯出」。它很快抓到方向，透過 Markdown-It 的渲染管線注入自訂樣式，再用 Puppeteer 無頭瀏覽器做高解析截圖。

樣板程式碼交給 AI

VS Code 擴充套件有不少樣板：package.json 的 contributes 設定、Extension Host 的生命週期管理、跟 Markdown-It 渲染引擎的串接。這些 Fable 5 大致都能生成可用的基礎架構，讓我比較能專注在主題引擎與匯出品質的調整。

一起處理技術細節

做「4x 高解析匯出」時，關鍵在 Puppeteer 的 deviceScaleFactor。我和 Fable 5 討論了幾種渲染策略，最後採用的做法是在無頭瀏覽器裡以 4 倍縮放渲染 SVG，再截取圖表區域：

const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();

await page.setViewport({
  width: 1280,
  height: 800,
  deviceScaleFactor: 4, // 4x 高解析渲染，約 384 DPI
});

// 注入 Mermaid SVG 並等待渲染完成
await page.setContent(htmlWithMermaidSvg);
const svgElement = await page.$('svg');

// 截取 SVG 元素，自動裁切到圖表邊界
const pngBuffer = await svgElement.screenshot({
  type: 'png',
  omitBackground: true, // 透明背景
});

思路不複雜：用 deviceScaleFactor: 4 讓瀏覽器以 4 倍像素密度渲染，再用 omitBackground: true 拿到透明背景。產出的 PNG 放進簡報，文字和線條會比 1x 清楚一些。

延伸：把同一套體驗做成 React 元件 react-super-mermaid

VS Code 擴充套件解決的是「在編輯器裡看圖、匯出圖」，但我自己跑部落格、做後台，也常常需要在網頁上直接渲染 Mermaid。於是我把 Super Mermaid 的核心體驗抽出來，另外做了一個開源的 React 元件庫 react-super-mermaid，發佈到 npm。

用法就是一行：

import { MermaidViewer } from 'react-super-mermaid'

<MermaidViewer code={mermaidCode} theme="colorful" />

它把擴充套件那套功能搬到瀏覽器端：內建 colorful / sketch 主題、平移縮放（svg-pan-zoom）、圖內搜尋，以及 1x / 2x / 4x 的 SVG / PNG 高解析匯出。設計上盡量輕量，mermaid 與 svg-pan-zoom 都是 optional peer dependencies、不會打包進 bundle，也做了 SSR 安全（Next.js 'use client'）、完整 TypeScript 型別與 ref 命令式 API，授權是 MIT。

簡單說，VS Code 用 Super Mermaid，網頁就用 react-super-mermaid，兩邊看到的圖會是同一種風格。介紹頁與安裝指令都放在 /tools/react-super-mermaid。

結論

Super Mermaid 主要是補上 VS Code 原生 Mermaid 在美化與匯出這兩段的不足，把比較瑣碎的步驟自動化。對常常用 Mermaid 跟 AI 溝通架構的人來說，一張清楚、好分享的圖，通常比一段長文字更省事，也更容易對齊彼此的理解。

有興趣的話可以到 VS Code Marketplace 下載 Super Mermaid，或到 GitHub 提 Issue、貢獻程式碼。

參考資料

• Mermaid GitHub — 85K+ stars
• VS Code 1.121 內建 Mermaid 渲染
• Mermaid + Claude Code 語境壓縮 — 3-6x token 效率
• Mermaid 圖表可讀性差 — Cursor 論壇
• Claude Fable 5（Anthropic 官方）
• Fable 5 在 GitHub Copilot 全面開放