作為一個經(jīng)常寫技術(shù)文檔、做方案匯報的人我對“畫圖”這件事又愛又恨。流程圖、時序圖、ER圖每一樣都離不開但桌面畫圖軟件要么收費要么操作繁瑣要么導(dǎo)出的圖片丑得沒法見人。直到我用上Mermaid Live Editor這個免費在線圖表編輯工具才算真正把畫圖這件事從“負(fù)擔(dān)”變成了“順手就做的事”。這篇文章我會把手頭這套玩法完整拆開為什么選它、核心語法怎么記、實際操作怎么用、怎么把它接到 Typora、macOS 上怎么打開還會附上一個可以直接復(fù)制跑的“學(xué)校教學(xué)管理 E-R 圖”完整示例。適合剛接觸 Mermaid 的新手也適合已經(jīng)會寫一點、想系統(tǒng)梳理流程的老手。1. 為什么我堅持用 Mermaid Live Editor 而不是桌面工具1.1 畫圖這件事的痛點以前畫流程圖我常用的路徑是打開 Visio、Draw.io 或者 ProcessOn用鼠標(biāo)拖拽方框、連線、對齊、調(diào)樣式。一張圖少說十分鐘多則半小時。問題還不是慢而是改圖最痛苦需求一變整個布局全亂重新拖一遍。等圖終于能看了想放進(jìn)文檔里又遇到圖片清晰度、格式統(tǒng)一、版本管理的問題。后來我開始用代碼畫圖PlantUML、Graphviz 都試過但它們要么語法繁瑣要么環(huán)境配置麻煩。Mermaid 是這里面最輕量、最順手的。而Mermaid Live Editor作為官方提供的在線編輯器把“寫代碼”和“看渲染結(jié)果”做到了同一個頁面左寫右看實時出圖連保存和導(dǎo)出都一并解決了。1.2 Live Editor 對比本地工具的優(yōu)勢我用過的方案不算少這里直接放一個對照表方便你判斷什么場景下選什么工具對比維度Mermaid Live Editor桌面畫圖軟件Visio/Draw.io本地編輯器 Mermaid 插件安裝成本無需安裝瀏覽器打開即用需要下載安裝部分收費需要安裝編輯器與插件上手門檻低記住少量語法即可較低拖拽即可但做復(fù)雜圖慢中等要看插件文檔改圖效率改代碼即改圖支持批量替換需要逐個調(diào)整元素效率高但依賴本地環(huán)境協(xié)作分享分享鏈接或代碼即可需要導(dǎo)出文件再發(fā)送需要同步代碼或文件導(dǎo)出格式PNG、SVG、Markdown 等格式多但部分收費取決于環(huán)境是否支持版本追蹤代碼是純文本可進(jìn) Git二進(jìn)制文件難以 diff天然支持代碼進(jìn)版本庫我能明顯感受到的差異是當(dāng)我把圖表以“代碼”形式嵌入到文檔工程里之后圖就不再是“一張不能改的圖片”而是“一段可以被 review、被復(fù)用、被部署的文本資產(chǎn)”。這在團(tuán)隊協(xié)作里價值極大。1.3 什么時候它并不合適說句公道話Mermaid Live Editor 不是萬能的。如果你的需求是畫復(fù)雜的架構(gòu)圖、嚴(yán)格像素級控制的視覺稿、或者帶有大量手繪風(fēng)格的示意圖它并不合適。比如畫一個精美的產(chǎn)品原型圖或者需要精確控制每個節(jié)點坐標(biāo)的網(wǎng)絡(luò)拓?fù)鋱D用 Mermaid 會非常痛苦。Mermaid 擅長的是“結(jié)構(gòu)化圖表”流程、時序、類關(guān)系、ER 關(guān)系、狀態(tài)流轉(zhuǎn)、甘特計劃。這些圖的特點是“內(nèi)容大于形式”讀者關(guān)心的是邏輯關(guān)系而不是美術(shù)效果。所以我的經(jīng)驗是能用結(jié)構(gòu)化方式表達(dá)的圖優(yōu)先用 Mermaid需要視覺精致度的圖才動用專業(yè)畫圖工具。2. Mermaid 語法速查夠用的核心子集2.1 流程圖 Flowchart最常寫的圖Flowchart 是 Mermaid 里使用頻率最高的一類核心語法就那么幾條看一遍就能上手。flowchart TD A[開始] -- B{判斷條件} B -- 是 -- C[執(zhí)行操作] B -- 否 -- D[結(jié)束]短短三行就畫出了一個帶分支的流程。TD 表示方向從上到下還有 LR 表示從左到右。節(jié)點里方括號[]表示矩形節(jié)點花括號{}表示決策節(jié)點圓括號()表示圓角節(jié)點這些記清楚基本就夠日常用了。連線方面--是普通箭頭---是實線-.-是虛線箭頭是加粗箭頭。2.2 時序圖 Sequence Diagram梳理交互必備寫接口調(diào)用、業(yè)務(wù)交互的時候時序圖是我最常用的。Mermaid 的時序圖語法跟畫圖工具里拖 lifeline 完全是兩種體驗寫起來非常快sequenceDiagram participant 用戶 participant 前端 participant 后端 用戶-前端: 點擊提交按鈕 前端-后端: POST /api/submit 后端--前端: 返回結(jié)果 前端--用戶: 展示反饋participant可以自定義參與者的展示名稱-表示實線箭頭--表示虛線返回。這就是時序圖的核心剩下的是把業(yè)務(wù)邏輯填進(jìn)去。注意消息文本后要跟冒號文本內(nèi)容里盡量別有特殊字符否則容易解析報錯。2.3 類圖與 ER 圖寫技術(shù)方案時靠它撐場面類圖和 ER 圖在 Mermaid 里寫法高度類似ER 圖用erDiagram聲明類圖用classDiagram聲明。ER 圖在數(shù)據(jù)建模、數(shù)據(jù)庫設(shè)計文檔中非常實用。erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains CUSTOMER { int id string name string email } ORDER { int id string status date created_at } LINE_ITEM { int id int product_id int quantity }這里||--o{表示“一”到“零或多”的關(guān)系Mermaid 用這些符號表示基數(shù)。寫 entity 字段時在花括號里寫類型 字段名即可語法非常簡單。類圖類似用/-表示可見性可以標(biāo)注方法。2.4 餅圖、甘特圖等其他類型偶爾救急也不錯除了上面三類Mermaid 還支持餅圖、甘特圖、狀態(tài)圖、旅程圖等。餅圖的語法更是簡單到令人發(fā)指pie title 項目時間分布 需求分析 : 20 開發(fā)編碼 : 50 測試修復(fù) : 30甘特圖適合做項目排期語法稍復(fù)雜需要定義日期和任務(wù)依賴關(guān)系。這些不常寫但當(dāng)別人都在用 Excel 做排期時你直接甩一個可視化甘特圖出來效果非常好。3. Live Editor 實操流程從打開頁面到導(dǎo)出圖片3.1 上手第一步打開頁面左右分欄Mermaid Live Editor 的界面非常簡潔打開后默認(rèn)是左右兩欄。左側(cè)是代碼區(qū)右側(cè)是預(yù)覽區(qū)。在左側(cè)輸入 Mermaid 代碼右側(cè)會實時渲染出圖。它會在你輸入的同時就更新基本感受不到延遲。第一次用的時候建議先把示例代碼全部刪掉自己從一行g(shù)raph TD開始敲感受一下“代碼即圖”的感覺。我常用的做法是先在 Live Editor 里把代碼調(diào)試到滿意再決定最終怎么使用。導(dǎo)出按鈕在預(yù)覽區(qū)的上方支持 PNG 和 SVG。SVG 的清晰度更好適合印刷和 PPT 里放大PNG 則適合直接粘貼到文檔中。3.2 三步定位語法錯誤寫代碼最容易碰到的就是語法錯誤。Mermaid 的報錯信息不算友好但定位問題其實有套路。首先看預(yù)覽區(qū)是否出現(xiàn)了錯誤提示框框里一般會描述錯誤類型。其次看左側(cè)代碼區(qū)有沒有紅色下劃線或波浪線標(biāo)記這些標(biāo)記通常就指向錯誤位置。最后如果還定位不了就用二分法把代碼注釋掉一半看是否恢復(fù)渲染逐步縮小問題范圍。常見錯誤有三種單引號或雙引號不匹配、中文字符誤寫成了全角符號、節(jié)點文字里出現(xiàn)了英文冒號和方括號的組合。3.3 導(dǎo)出高清圖的參數(shù)選擇導(dǎo)出圖片時PNG 格式有個縮放選項可以選擇。很多人在這一步只縮放寬度結(jié)果導(dǎo)出后字體模糊。我的經(jīng)驗是如果圖片要放進(jìn)印刷材料直接導(dǎo)出 SVG如果只能傳 PNG把寬高設(shè)置成實際用圖的兩倍再把圖片等比縮小放進(jìn)來清晰度會好很多。另外Live Editor 還支持直接復(fù)制 Markdown 格式它會生成一段帶代碼塊的 Markdown 文本粘到支持 Mermaid 的平臺里就能直接渲染。這種方式非常適合寫博客和文檔。4. 教學(xué)管理 E-R 圖案例一份可以直接抄的 Mermaid 代碼4.1 需求拆解網(wǎng)上熱搜詞里有“學(xué)校教學(xué)管理 E-R 圖”需求我在做數(shù)據(jù)建模方案時也經(jīng)常被問到這塊。教學(xué)管理涉及的核心實體不外乎學(xué)生、教師、課程、班級、成績。關(guān)系上一個班級有多名學(xué)生一個學(xué)生可選多門課程一個教師教多門課程一個學(xué)生修一門課程會有一個成績。這些用 ER 圖表達(dá)非常合適。先理清楚實體和關(guān)系再動手寫代碼這也是寫 Mermaid 的通用思路先有邏輯再有代碼。4.2 完整代碼與說明下面這段代碼是我實際在用的一份教學(xué)管理 E-R 圖可以直接復(fù)制到 Mermaid Live Editor 或任何支持 Mermaid 的平臺運行。erDiagram SCHOOL_CLASS ||--o{ STUDENT : 包含 TEACHER ||--o{ COURSE : 講授 STUDENT ||--o{ ENROLLMENT : 選擇 COURSE ||--o{ ENROLLMENT : 接收 ENROLLMENT }o--|| SCORE : 對應(yīng) SCHOOL_CLASS { int class_id PK string class_name int grade string major } STUDENT { int student_id PK string student_name string gender date birth_date int class_id FK } TEACHER { int teacher_id PK string teacher_name string title string department } COURSE { int course_id PK string course_name int credit int teacher_id FK } ENROLLMENT { int student_id FK int course_id FK date enroll_date } SCORE { int student_id FK int course_id FK int score_value string grade_level }代碼里有幾點值得注意。實體名我用的全大寫這是 ER 圖常見慣例。每個實體的主鍵標(biāo)了PK外鍵標(biāo)了FK關(guān)系上用了||--o{來表達(dá)一對多。ENROLLMENT本質(zhì)上是學(xué)生和課程之間的關(guān)聯(lián)實體成績從屬于選課關(guān)系所以我把成績表和選課表之間用}o--||連接邏輯上更嚴(yán)謹(jǐn)。4.3 如何把這個圖用到文檔、PPT、論文里代碼寫好了實際落地有三個路徑。路徑一是直接在 Live Editor 里導(dǎo)出 PNG/SVG放進(jìn) Word、PPT、論文里這是最通用的方式。路徑二是把代碼塊粘到支持 Mermaid 的 Markdown 編輯器里比如 Typora、Obsidian、GitHub、語雀保存后自動渲染。路徑三是把代碼放進(jìn)項目倉庫用 Mermaid CLI 在 CI 流程里自動生成圖片這套適合文檔持續(xù)更新的團(tuán)隊。我個人最推薦第二種因為圖跟文檔在同一個地方維護(hù)改圖時不用重新截圖。5. 高頻場景問答Typora 升級 Mermaid、Mac 打開、以及那些“卡殼”瞬間5.1 在 Typora 里使用和升級 Mermaid 渲染Typora 原生支持 Mermaid這功能很多人知道。在 Typora 里新建一個代碼塊語言選mermaid然后寫語法退出代碼塊圖就會自動渲染。但如果你用的 Typora 版本比較舊可能會遇到語法不支持、新類型圖渲染不了的情況。Typora 本身不提供插件機制它的 Mermaid 渲染能力直接內(nèi)置在軟件版本里。所以所謂“升級 Mermaid”實際上是升級 Typora 軟件版本。操作路徑是Typora 菜單欄 - 偏好設(shè)置 - 通用 - 檢查更新。如果你用 macOS可以直接在“關(guān)于 Typora”里看版本號然后去官網(wǎng)下載最新版覆蓋安裝。升級前要注意備份主題和自定義樣式不過 Typora 升級一般不會動用戶配置覆蓋安裝風(fēng)險很低。升級后那些新增的圖表類型比如mindmap、timeline就能正常渲染了。5.2 macOS 用戶如何打開和使用macOS 下打開 Mermaid Live Editor 很簡單打開瀏覽器Safari、Chrome 都行直接在地址欄輸入 mermaid.live 或者 mermaid.ink 等官方網(wǎng)址回車就是。不需要安裝任何東西。如果你想在本地寫 MermaidmacOS 上常用的方案有 Typora、VS Code 裝 Markdown Preview Mermaid Support 插件、Obsidian。有一個小坑是如果你用 Safari 打開 Live Editor部分版本的導(dǎo)出 PNG 功能可能行為異常。這時候換個 Chrome 或者 Edge 就好了。另外macOS 的預(yù)覽工具沒法直接預(yù)覽.mmd文件所以如果你把 Mermaid 代碼保存成了.mmd后綴文件想預(yù)覽還是得打開 Live Editor 或 VS Code 插件。5.3 Live Editor 之外的工作流整合Live Editor 適合單次畫圖但如果在項目里頻繁用圖建議把 Mermaid 代碼直接放進(jìn)文檔工程。GitHub 和 GitLab 的 Markdown 渲染都原生支持 Mermaid代碼塊標(biāo)mermaid語言就可以。VS Code 里裝插件后Markdown 預(yù)覽也能渲染 Mermaid。Obsidian 更是把 Mermaid 當(dāng)作一等公民代碼塊直接渲染不需要額外配置。我的習(xí)慣是項目文檔里統(tǒng)一使用 Mermaid 代碼塊畫圖圖片不單獨存放。這樣代碼評審時圖的變化可以 diff版本管理也不會出現(xiàn)“圖更新了但文檔忘記改”的問題。6. 常見報錯與排查技巧實錄6.1 報錯速查表實踐里經(jīng)常碰到的問題我整理成了一張速查表報錯現(xiàn)象可能原因解決辦法Syntax error in text節(jié)點文字里有未轉(zhuǎn)義的特殊字符給文字加引號或用#轉(zhuǎn)義圖形預(yù)覽空白代碼塊開頭少了類型聲明檢查是否寫了flowchart、sequenceDiagram等聲明方向不對忘記指定TD/LR在 flowchart 后加上方向參數(shù)中文亂碼編碼問題或字體缺失確認(rèn)文件保存為 UTF-8導(dǎo)出圖片時選 SVG時序圖消息不顯示消息文本前漏了冒號檢查-、--后面是否有冒號和空格ER 圖關(guān)系不顯示關(guān)系符號寫錯確認(rèn)使用 6.2 幾個我踩過的坑第一個坑是英文雙引號和中文引號混用。Mermaid 對引號非常敏感有時候報錯提示根本不指向真正的問題行而是指向下一行。排查時先看有沒有全角符號這是最常見的隱形殺手。第二個坑是節(jié)點 ID 和文字問題。Mermaid 的節(jié)點 ID 不能包含空格也不能用純數(shù)字開頭。如果你寫A[這是一個節(jié)點]ID 是 A文字是括號里的內(nèi)容這沒問題。但如果你括號里的文字包含英文方括號比如[用戶[管理員]]就會解析失敗。解決辦法是給文字加上雙引號A[用戶[管理員]]。第三個坑是圖太大超出頁面。Live Editor 的預(yù)覽區(qū)有縮放按鈕但如果你導(dǎo)出的圖在文檔里顯示太小不要放大圖片而是應(yīng)該調(diào)整渲染參數(shù)比如 flowchart 的節(jié)點間距或字體大小。第四個坑我花了不少時間才搞明白同一張圖里的實體名不能重復(fù)。在 ER 圖里如果你不小心把兩個實體定義成同名Mermaid 會直接報錯甚至卡住。命名時我習(xí)慣給實體加前綴比如SYS_USER、BIZ_ORDER既避免沖突又讓語義更清晰。7. 這套工作流我還在繼續(xù)擴展寫到最后說點我自己的真實體會。Mermaid Live Editor 解決了我 80% 的日常畫圖需求剩下的 20% 我會結(jié)合截圖、手繪圖或者其他專業(yè)工具去補。但核心思路始終是能用文本表達(dá)的圖表堅決不用鼠標(biāo)拖拽。因為文本可以版本管理、可以搜索、可以復(fù)用這一優(yōu)勢在長期維護(hù)的文檔里體現(xiàn)得尤其明顯。最后再分享一個小技巧如果你經(jīng)常寫 Mermaid可以在瀏覽器里把 Live Editor 加到書簽同時把代碼組織成自己的“代碼片段庫”。我就在電腦里存了一個mermaid-snippets.md文件把常用的 flowchart 模板、時序圖模板、ER 圖模板都放在里面要用的時候復(fù)制改改就行基本不用從零開始寫。效率提升非常明顯建議你也試試。