Mermaid 概述

了解 Mermaid 的架構、渲染流程、支援的圖表類型，以及最常見的渲染失敗原因

Overview##

Mermaid 是一套以文字描述圖表的 JavaScript 工具。你用類似 Markdown 的語法寫圖表定義，Mermaid 將它渲染成 SVG。

傳統做法是用 Figma、Draw.io 畫圖，匯出圖片，再嵌入文件。問題是圖片無法被版本控制追蹤差異，修改一個箭頭就要重新匯出。Mermaid 讓圖表變成純文字，可以跟程式碼一起 commit、review、diff。

flowchart LR
    A["Text Definition"] --> B["Mermaid Parser"]
    B --> C["SVG Output"]

Architecture##

渲染流程###

Mermaid 的渲染分為三個階段：

flowchart TD
    A["Markdown Code Block"] --> B["Detect diagram type"]
    B --> C["Parse syntax to AST"]
    C --> D["Apply theme + config"]
    D --> E["Render to SVG"]
    E --> F["Insert into DOM"]

Detection — 從第一行判斷圖表類型（flowchart、sequenceDiagram 等）
Parsing — 將文字語法解析為抽象語法樹（AST），語法錯誤在這裡被攔截
Rendering — 根據 AST 和 theme 設定產生 SVG，插入頁面 DOM

Note

Parsing 階段是最容易出錯的地方。Mermaid 的 parser 對特殊字元、縮排、箭頭語法有嚴格要求，一個字元錯就會導致整張圖渲染失敗。

Build-time vs Client-side Rendering###

方式	工具	優點	缺點
Build-time	`remark-mermaidjs`	零 JS、SEO 友善	需要 Playwright（~100MB）
Client-side	`mermaid` npm package	零額外依賴、設定簡單	需載入 JS、首次渲染有閃爍

大多數文件站（包括本站）使用 client-side rendering，因為 build-time 方案需要安裝 Playwright 做 headless browser 渲染，對 CI/CD 環境造成額外負擔。

Security Levels###

Mermaid 有四種安全層級，控制渲染時的行為：

Level	說明	適用場景
`strict`	預設值，禁止 JavaScript 執行和 click events	大多數場景
`loose`	允許 click callback 和部分 HTML	信任的內容
`antiscript`	允許 HTML，但會移除 `script` 元素；click 功能仍啟用	需要較寬鬆 HTML、但不想完全放開腳本
`sandbox`	在 iframe 中渲染，最大隔離	使用者提供的不信任內容

mermaid.initialize({
  securityLevel: 'strict', // recommended for documentation sites
});

Warning

如果你的圖表包含使用者輸入的內容，優先使用 strict 或 sandbox。loose 和 antiscript 都會放寬 HTML / 互動限制，只適合你明確信任內容來源的場景。

Supported Diagram Types##

Mermaid 目前支援以下圖表類型：

類型	關鍵字	用途
Flowchart	`flowchart`	流程圖、決策樹、系統架構
Sequence Diagram	`sequenceDiagram`	API 呼叫、系統互動時序
Class Diagram	`classDiagram`	物件導向設計、型別關係
State Diagram	`stateDiagram-v2`	狀態機、生命週期
ER Diagram	`erDiagram`	資料庫 schema、實體關係
Pie Chart	`pie`	比例分佈
Gantt Chart	`gantt`	專案排程、時間線
Git Graph	`gitgraph`	Git branch 流程
Mindmap	`mindmap`	概念發散、腦力激盪

Tip

文件站最常用的是 Flowchart（架構圖）和 Sequence Diagram（API 互動）。其他類型視需求使用。

Troubleshooting##

Mermaid 最大的痛點是渲染失敗時只會顯示錯誤訊息或空白，不告訴你哪一行出錯。以下是最常見的原因：

1. CJK 字元中的特殊符號###

中文括號 （）、全形冒號 ： 會被 parser 誤判為語法符號。

BAD:
sequenceDiagram
    App->>Server: 授權請求（附 scope）

GOOD:
sequenceDiagram
    App->>Server: Authorization Request with scope

Warning

Mermaid 的 label 和 message 建議使用英文。如果必須用中文，避免中文括號和全形標點。

2. Label 中的箭頭和特殊字元###

->、<、>、{}、[] 在 Mermaid 中都有語法意義。放在 label 中會導致 parse error。

BAD:
flowchart LR
    A[Config -> Deploy]

GOOD:
flowchart LR
    A["Config -> Deploy"]

用雙引號包裹含有特殊字元的 label。

3. 缺少空格###

箭頭前後需要空格，否則 parser 無法正確分割 token。

BAD:
flowchart TD
    A-->B

GOOD:
flowchart TD
    A --> B

4. HTML Entity 編碼###

當 Mermaid code block 被 Shiki（程式碼高亮工具）處理後，>> 會被轉成 >>。如果在渲染前沒有正確解碼，Mermaid 會收到錯誤的輸入。

HTML output:  App-&gt;&gt;Server: message
Expected:     App->>Server: message

本站在 DocLayout.astro 中使用 innerText（而非 textContent）來提取 code block 內容，確保 HTML entities 被正確解碼。

5. Code Fence 後有空格###

BAD:
```mermaid  ← trailing space
flowchart TD
    A --> B
```

GOOD:
```mermaid
flowchart TD
    A --> B
```

6. 未宣告 Participant###

Sequence diagram 中如果沒有明確宣告 participant，Mermaid 會嘗試自動推斷，但在複雜圖表中容易出錯。

BAD:
sequenceDiagram
    A->>B: message

GOOD:
sequenceDiagram
    participant A
    participant B
    A->>B: message

除錯技巧###

使用 Mermaid Live Editor — 在 mermaid.live 貼上你的語法，即時看到渲染結果和錯誤訊息
開啟 debug log — mermaid.initialize({ logLevel: 'debug' }) 會在 console 輸出詳細的 parsing 過程
逐步刪減 — 如果一張複雜的圖渲染失敗，從最小的版本開始，逐步加入 node 和 edge，找到出錯的那一行

Summary##

Mermaid 將文字描述轉換為 SVG 圖表，讓圖表可以版本控制
渲染流程：Detection → Parsing → Rendering，語法錯誤在 Parsing 階段被攔截
文件站建議使用 client-side rendering，避免 Playwright 的 build-time 依賴
最常見的渲染失敗原因：CJK 特殊符號、label 中的箭頭字元、缺少空格、HTML entity 編碼
Label 中有特殊字元時用雙引號包裹，Sequence diagram 建議明確宣告 participant
善用 mermaid.live 做即時除錯

留言 (0)

登入後即可留言