很多團隊的流程圖一直停留在“畫一遍、改一遍、再重畫一遍”的狀態。產品邏輯變了流程圖要重畫需求文檔更新了架構圖要重畫評審會上大家對著圖爭論回頭發現圖又落后于代碼。真正的問題不是畫圖的技巧而是流程圖的存儲形式不對它被存成了沒法 diff、沒法版本管理、沒法自動生成的畫布文件。這次我們看的這個項目思路標題就直接點出了解法Mermaid flowcharts you dont have to redraw in a diagram editor意思是讓 Mermaid 流程圖以代碼形式存在渲染結果交給 Mermaid而不是再回到 diagram editor 里手工重繪。Mermaid 是一套基于 JavaScript 的圖表渲染引擎用類似 Markdown 的文本語法描述流程圖、時序圖、類圖、狀態圖、ER 圖、甘特圖等。寫的是代碼塊出的是矢量圖。開發者和文檔工程師維護的是 .mmd 文件或 Markdown 中的 mermaid 代碼塊圖的邏輯結構就在文本里大家可以在 Git 里逐個字符地 review 變更。整個過程不再需要拖拽畫布、對齊節點、微調連線。這篇文章不會只講概念重點放在四件事上第一Mermaid 流程圖如何用代碼定義為什么不需要在 diagram editor 里重繪第二本地編輯環境怎么搭瀏覽器、VS Code、命令行三個入口怎么選第三如何用 mermaid-cli 做批量導出和接口化調用第四從語法、渲染、性能到常見坑的完整驗證流程。適合讀者很明確后端開發、文檔工程師、運維同學以及所有“畫圖五分鐘、改圖半小時”的人。只要有一臺普通辦公電腦裝好 Node.js命令行能用剩下的事就是寫語法。1. Mermaid 核心能力速覽在動手之前先把 Mermaid 這個方案的能力邊界看清楚。下面的表格是把 Mermaid 生態里最常用的幾個入口mermaid.live、mermaid-cli、VS Code 預覽插件放在一起評估的結果具體版本和細節以實際安裝為準但整體能力分布不會變。能力項說明項目類型基于 Mermaid 的代碼化圖表渲染方案核心價值流程圖以文本代碼維護渲染與重繪分離無需手工重畫支持的圖表類型流程圖flowchart、時序圖、類圖、狀態圖、ER 圖、甘特圖、餅圖、用戶旅程圖、思維導圖、時間線等具體取決于版本運行環境瀏覽器、Node.js、VS Code 擴展、Docker硬件門檻極低普通 CPU 即可無顯卡要求主要工具mermaid.live、mermaid-js/mermaid-cli、VS Code 預覽擴展是否支持 API支持命令行為主也有在線渲染接口和自建服務方案是否支持批量任務支持CLI 可批量轉換 .mmd / .md 文件輸出格式SVG、PNG、PDF、HTML 等按 CLI 參數配置適合場景技術文檔、架構評審、需求分析、代碼注釋、CI 文檔生成從整個生態看最成熟的兩條路徑是日常編輯用 VS Code 加預覽插件改代碼就看到圖自動化場景用 mermaid-cli 批量渲染接到 CI 流水線里。兩條路徑都不需要你打開傳統的拖拽式畫圖工具。后面每一章都會圍繞這兩條路徑展開。2. 適用場景與使用邊界這個思路適合誰一句話概括任何需要“圖表跟隨文檔版本一起演進”的人。代碼化流程圖的收益在單張圖上不明顯在持續變更的文檔體系里非常明顯。每次需求變更改的是幾行文本而不是重新拖一遍畫布。具體來說適合這些場景。第一類是技術方案文檔直接在 Markdown 里內嵌 mermaid 代碼塊提交到 Git評審時看渲染結果reviewer 能看到流程圖邏輯的精確 diff。第二類是接口流程說明時序圖用代碼寫接口變更后同步改文本即可不會出現代碼和文檔兩張皮。第三類是架構圖、狀態機、ER 圖用代碼維護比拖拽對齊更快最重要的是 diff 可讀哪條連線變了、哪個節點加了一眼就能看出來。第四類是 CI/CD 自動更新文檔改完代碼流水線自動生成最新圖表并發布到內部 Wiki。第五類是博客和知識庫Markdown 直接渲染發布平臺原生支持或插件支持。不太適合的場景也要說清楚。如果追求像素級視覺設計比如對外宣傳圖、UI 交互稿Mermaid 的可視化定制能力有限顏色、字體、布局的精細控制都不如專業繪圖軟件。如果圖特別大幾百個節點以上Mermaid 布局算法容易失控需要拆圖或考慮 Graphviz 等其他方案。如果使用者是完全不碰代碼的業務同學學習成本主要在語法而不是工具操作這時候要評估是教語法還是繼續用畫圖工具。使用邊界方面Mermaid 本身只是純客戶端圖表渲染不涉及數據上傳但工程上要注意合規。在線版 mermaid.live 渲染時靠瀏覽器本地執行代碼本身會進入頁面會話不要把你公司的敏感架構圖貼到不受控的公共服務上。涉及保密項目的架構、賬號體系、數據庫拓撲、內部域名和 IP建議一律本地 CLI 渲染。對外發布前檢查節點文本是否包含內部信息片段這是很多人容易忽略的一步。3. Mermaid 本地部署與編輯環境準備先講環境。Mermaid 對硬件幾乎沒要求普通辦公機、虛擬機、云服務器都行不需要 GPU也不需要大內存。真正要花時間準備的是 Node.js 運行時、包管理器和編輯器以及 mermaid-cli 導出圖片時依賴的無頭瀏覽器內核。需要準備的核心環境按優先級排列Node.js建議安裝 LTS 版本mermaid-cli 基于它運行npm 或 yarn隨 Node.js 自帶 npmVS Code 編輯器配合預覽插件使用Chrome 或 Edge 瀏覽器用于交互式驗證渲染結果還有一個隱藏依賴mermaid-cli 導出 PNG/PDF 時通過 Puppeteer 拉起 Chromium 內核安裝 CLI 時會自動拉取磁盤會多占用幾百 MB 到 1GB 左右。環境準備階段先跑一遍通用檢查清單# 檢查 Node.js 是否安裝 node -v # 檢查 npm 是否可用 npm -v # 檢查當前 npm 源按需切換鏡像 npm config get registry如果 node -v 沒有輸出版本號先去 Node.js 官網下載 LTS 安裝包一路默認安裝然后重新打開終端再驗證。國內網絡環境如果 npm 安裝依賴經常失敗把 registry 切到鏡像源會省很多時間這一步在做 mermaid-cli 安裝之前最好先完成。關于版本Mermaid 和 mermaid-cli 都在持續更新不同版本對語法支持有差異。第一次使用建議直接用最新穩定版不要拿很老的教程硬套尤其是子圖、方向、樣式這些語法在不同版本里的行為不完全一致。項目里如果要復用建議把 CLI 版本固定下來避免升級后渲染效果變化導致文檔里的圖全部換樣。4. Mermaid 安裝部署與啟動方式4.1 VS Code 插件方式這是日常寫文檔最舒服的入口。在 VS Code 擴展商店搜索 Mermaid安裝 Markdown Preview Mermaid Support 這類預覽插件。插件的作用是在 Markdown 預覽時自動識別 mermaid 代碼塊并渲染成圖。安裝后新建或打開一個 Markdown 文件寫入 mermaid 代碼塊graph TD A[需求分析] -- B[方案設計] B -- C[開發實現] C -- D[測試驗收] D -- E[發布上線]按 Markdown 預覽快捷鍵圖表直接渲染。改代碼預覽實時刷新完全不用重畫。這就是標題里 dont have to redraw 在編輯環節的體現。整個體驗和寫 Markdown 一樣是“文本輸入加即時反饋”而不是“拖拽對齊加手動連線”。4.2 mermaid.live 在線編輯器如果只想快速驗證一段語法不想本地裝任何東西直接打開 mermaid.live 即可。左邊是語法代碼右邊是實時渲染結果頂部可以導出 PNG/SVG還可以把代碼加密后生成共享鏈接發給同事。這個入口適合三件事驗證新寫的語法是否正確給同事演示某個流程或者臨時畫一張小圖直接導出用。需要注意在線頁面渲染確實在瀏覽器本地完成但你把共享鏈接發給別人時代碼內容會經過第三方服務處理。公司內部架構、客戶數據、賬號體系流程不要走這個入口。更穩妥的做法是本地 CLI 渲染導出圖片后再發。4.3 mermaid-cli 命令行方式批量場景、CI 場景、API 場景都必須用命令行工具。mermaid-cli 的官方包名是 mermaid-js/mermaid-cli安裝方式如下# 全局安裝方便命令行直接調用 npm install -g mermaid-js/mermaid-cli # 查看幫助 mmdc -h安裝完成后寫一個輸入文件 test.mmdgraph LR A[用戶請求] -- B[網關] B -- C[服務A] B -- D[服務B] C -- E[(數據庫)]執行轉換命令# 輸出 SVG mmdc -i test.mmd -o test.svg # 輸出 PNG指定背景色和寬度 mmdc -i test.mmd -o test.png -b white -w 1200 # 輸出 PDF mmdc -i test.mmd -o test.pdf第一次運行 mmdc 時CLI 會自動定位或下載 Chromium 內核如果下載失敗會報 Puppeteer 相關錯誤。這個問題非常常見后面排查章節會給方案。命令執行成功后同目錄下會出現對應格式的圖片文件用瀏覽器打開 SVG 可以確認渲染內容和預期一致。4.4 Docker 方式如果不想在宿主機裝完整 Chromium或者需要固定版本跑自動化任務可以用 Docker 封裝 mermaid-cli。社區和官方都有容器鏡像通用做法是把本地目錄掛載進容器再執行 mmdcdocker run --rm -v $(pwd):/data ghcr.io/mermaid-js/mermaid-cli/mermaid-cli -i /data/test.mmd -o /data/test.svg具體鏡像名以你選擇的倉庫說明為準上面的命令只是通用示例。Docker 方式的好處是環境隔離、版本固定不會因為某臺機器缺 Node 依賴而失敗適合放進自動化流水線。缺點是多一層容器管理的復雜度對單機用戶來說直接用 CLI 更省事。5. Mermaid 基本用法與核心語法代碼繪圖代替手工重繪整個思路成立的關鍵是把流程圖的“邏輯結構”和“視覺渲染”分離。你在 Mermaid 里描述的是節點和連邊關系布局引擎負責把節點自動擺放、連線自動路由。下面這段代碼就是完整的流程圖定義flowchart TD A[開始] -- B{是否有權限} B -- 是 -- C[進入系統] B -- 否 -- D[返回登錄頁]這段代碼表達的含義非常明確方向是 TD即從上到下節點 A 是矩形內容為“開始”節點 B 是菱形內容為“是否有權限”B 到 C 的連線標簽是“是”B 到 D 的連線標簽是“否”。注意這里沒有定義任何坐標沒有拖動沒有對齊。渲染器根據節點之間的連接關系自動完成布局。這意味著三個直接收益。第一重構圖結構時只改文字和連線位置不用管。新增一個分支就是在文本里加一行箭頭刪掉一個環節就是刪一行視覺布局自動重排。第二代碼可以放進 Git提交記錄里能看到流程圖邏輯的歷史變更。流程圖和代碼一樣有版本一樣能回溯這是畫布文件做不到的。第三多個文檔可以復用同一段節點定義。把公共流程抽成片段寫進各自的文檔里更新時只改一處語義不用再手工同步多張圖。常用語法要點整理如下語法作用graph TD / graph LR / flowchart TB定義圖類型與方向A[文本]矩形節點A(文本)圓角矩形節點A{文本}菱形判斷節點A -- B有向連線A --- B無箭頭連線A -- 標簽 --- B帶標簽連線subgraph 標題子圖分組classDef / class節點樣式定制這里只列了最常用的部分完整語法建議參考 Mermaid 官方語法手冊。實際書寫時先用 mermaid.live 快速驗證一段語法確認渲染效果后再粘回文檔這段驗證過程大概 30 秒比在畫圖軟件里對齊節點快得多。6. Mermaid 功能測試與效果驗證環境準備好之后建議按下面這套流程做一輪功能驗證。不用一次全測按自己的場景挑幾項即可。6.1 基礎渲染測試測試目的確認 mermaid 代碼能正常渲染成圖。輸入示例為一個帶判斷分支的流程flowchart LR A(輸入) -- B{校驗} B --|通過| C[處理] B --|失敗| D[報錯]操作步驟很簡單。先把代碼粘貼到 mermaid.live 左側觀察右側是否出現兩條分支的流程圖再用 VS Code 的 Markdown 預覽驗證同一個代碼塊確認兩種環境的渲染結果一致。預期結果是左右兩側圖中節點文字和連線標簽都正常顯示能清楚看出“輸入 - 校驗 - 通過/失敗 - 處理/報錯”的完整路徑。常見的失敗情況是節點文字包含括號、引號等特殊字符時渲染異常。解決辦法是用雙引號把節點文字包起來例如 A[用戶 ID (uid)]這樣括號就不會被 Mermaid 當成語法邊界。6.2 時序圖測試測試目的驗證代碼描述時序邏輯的能力這是接口文檔里最常見的場景。輸入示例sequenceDiagram participant U as 用戶 participant S as 服務端 participant D as 數據庫 U-S: 登錄請求 S-D: 查詢用戶 D--S: 返回結果 S--U: 登錄成功預期結果是生成用戶、服務端、數據庫三個泳道消息按順序從上到下排列返回消息用虛線表示。這個圖能直接表達接口調用順序和異步返回關系比文字描述直觀得多。如果參與角色很多可以給 participant 加別名避免長名字把圖撐得太寬。6.3 子圖與樣式測試測試目的驗證復雜流程的組織能力尤其是多個服務或模塊的分組展示。輸入示例flowchart TB subgraph 訂單服務 A[創建訂單] -- B[扣減庫存] end subgraph 支付服務 C[發起支付] -- D[支付回調] end B -- C預期結果是兩個子圖分別框住各自節點子圖之間的連線從 B 指向 C。如果渲染出來的子圖位置不理想這是布局引擎的常見現象可以調整子圖定義順序或給子圖加 id 來控制。但建議不要在這上面花太多時間代碼化繪圖的收益是邏輯維護不是像素級布局。6.4 批量文件轉換測試測試目的確認 CLI 批量處理能力這決定了能不能接到自動化流程里。先準備一個目錄diagrams/ ├── login-flow.mmd ├── order-flow.mmd └── deploy-flow.mmd執行批量轉換命令mkdir -p output for f in diagrams/*.mmd; do mmdc -i $f -o output/$(basename ${f%.mmd}).svg done預期結果是 output 目錄下出現三個 SVG 文件文件名與輸入對應。判斷標準是所有文件都能生成且 SVG 里能看到對應節點文字沒有空圖和報錯中斷。7. Mermaid 接口 API 與批量任務Mermaid 的接口能力分三個層次從簡單到可控按需選擇。7.1 CLI 調用mermaid-cli 本身就是最穩定的接口把 .mmd 文件交給 mmdc得到 SVG/PNG/PDF適合接進腳本、CI 流水線、文檔生成系統。一個簡單的 Python 批量調用示例import subprocess from pathlib import Path diagrams_dir Path(./diagrams) output_dir Path(./output) output_dir.mkdir(exist_okTrue) for mmd_file in diagrams_dir.glob(*.mmd): out_svg output_dir / f{mmd_file.stem}.svg subprocess.run( [mmdc, -i, str(mmd_file), -o, str(out_svg)], checkTrue, )這段代碼會把 diagrams 目錄下所有 .mmd 文件逐個轉換為同名 SVG。注意 checkTrue 表示任一文件失敗就會拋出異常生產環境建議捕獲異常并記錄日志避免一個壞文件中斷整批任務。7.2 mermaid.ink 在線接口mermaid.ink 是把 mermaid 代碼編碼后通過 URL 獲取渲染圖片的服務適合在文檔里引用動態生成的圖表。請求格式一般是把 mermaid 代碼做 base64 編碼后拼到 URL 里# 先對 mermaid 代碼做 base64 編碼再拼接到 URL curl https://mermaid.ink/img/{base64編碼的代碼}在線服務可能隨時調整實際使用前先查看對應服務說明。如果涉及內部流程不推薦把代碼明文放進 URL一方面有長度限制另一方面有泄露風險。這個接口更適合公開文檔或臨時演示。7.3 自建渲染服務更可控的做法是自己包一個渲染服務把 mermaid-cli 包裝成 HTTP 接口輸入流程圖代碼輸出 SVG/PNG。下面是一個 Spring Boot 風格的偽代碼表達“包裝 CLI 為 API”的思路PostMapping(/render) public String render(RequestBody String mermaidCode) throws Exception { Path input Files.createTempFile(diagram, .mmd); Files.writeString(input, mermaidCode); Path output Files.createTempFile(diagram, .svg); Process p new ProcessBuilder(mmdc, -i, input.toString(), -o, output.toString()) .inheritIO().start(); p.waitFor(); return Files.readString(output); }注意這只是偽代碼不是可直接運行的實現。生產環境要加超時、限流、臨時文件清理和權限控制否則每次請求拉起一個 Chromium 進程并發一高機器就會吃緊。批量任務的工程化建議輸入和輸出目錄分離每次任務生成獨立日志單個文件失敗不中斷整個批次產物按日期或版本號歸檔。8. 資源占用與性能觀察資源占用是很多人在意、但官方文檔不細講的部分這里單獨說。Mermaid 渲染本身非常輕在瀏覽器或 VS Code 里渲染一張常規流程圖CPU 和內存占用可以忽略普通筆記本無壓力。真正的資源開銷來自 mermaid-cli 導出 PNG/PDF 時拉起的 Chromium 內核因為它是通過無頭瀏覽器渲染再截圖或打印。觀察方法很直接執行 mmdc 時另開一個終端用 top 或任務管理器觀察 chromium 進程大圖導出 PNG 時CPU 會短時拉高這是正常現象內存占用取決于 Chromium 內核加載通常幾百 MB 級別具體以本機測試為準。影響性能的主要因素因素影響節點數量幾百個節點以上布局算法耗時明顯增加輸出格式PNG 需要渲染后截圖比 SVG 直接輸出慢圖片尺寸-w -h 越大截圖耗時越長批量數量串行批量會累積等待時間建議控制并發數字體加載離線環境字體缺失會拖慢渲染或導致中文亂碼降低開銷的方法很明確。不需要位圖時一律輸出 SVGSVG 是矢量格式直接由渲染內核輸出速度快且無失真。PNG 導出的寬度按文檔實際需要設置不要無腦放大。批量任務限制并發比如同時跑兩到三個 mmdc 進程避免機器卡死。大圖建議拆分成多個子圖分別渲染再合并到文檔里。接口服務場景要特別注意如果每個請求都拉起一個 Chromium 進程并發高時機器壓力很大。生產化的建議是常駐一個渲染服務復用瀏覽器實例或者在容器里做進程池。具體怎么做要看實際架構但“每次請求拉起一個瀏覽器”的方案只適合低并發內網工具。9. Mermaid 常見問題與排查方法問題現象可能原因排查方式解決方案mmdc 命令找不到CLI 未安裝或 PATH 未更新執行 npm list -g mermaid-js/mermaid-cli重新全局安裝或使用 npx 調用首次運行卡在瀏覽器下載Puppeteer 拉取 Chromium 失敗查看終端輸出中的下載鏈接和錯誤碼配置鏡像或改用系統 Chrome設置 PUPPETEER_EXECUTABLE_PATH報錯 Cannot find module puppeteerCLI 依賴未完整安裝檢查 node_modules 目錄刪除 node_modules 后重新安裝圖內中文顯示為方塊字體缺失或 SVG 字體不匹配查看生成的 SVG 中 font-family安裝中文字體導出時指定字體配置節點文本含括號導致報錯特殊字符未轉義復制報錯信息到 mermaid.live 復現節點文字用雙引號包裹如 A[用戶(ID)]Markdown 預覽不渲染插件未加載或代碼塊語言標簽錯誤檢查代碼塊是否寫為 mermaid確認代碼塊標簽正確且插件已啟用SVG 背景為透明無法查看SVG 默認透明檢查使用場景導出時指定 -b white批量轉換中途卡住單個文件語法錯誤或內存占用高定位卡住的文件單獨執行該文件修復語法或增加超時和失敗重試在線鏈接打不開鏈接過期或服務不可用重新復制代碼生成新鏈接使用本地 CLI 或自行部署渲染服務這里有兩個容易踩的坑值得單獨強調。第一個是 npm 網絡源不穩定時mermaid-cli 安裝失敗概率很高先把 registry 切到鏡像源再安裝能省很多時間。第二個是不要把在線編輯器里寫好的敏感圖表直接生成共享鏈接發給別人內部架構圖、數據庫表結構、賬號體系流程一律本地渲染后再傳播。10. Mermaid 最佳實踐與使用建議把這些實踐沉淀下來代碼化流程圖才能真正替代 diagram editor 的工作流而不是又變成一套沒人維護的代碼。下面幾條是按優先級排的。先從最小閉環開始。第一次使用先畫一張十幾節點的流程圖跑通 VS Code 預覽、CLI 導出、Git 提交全流程再決定是否全團隊推廣。不要一開始就畫上千節點的大圖布局不理想后容易懷疑工具不行實際上是使用姿勢問題。建立目錄規范。把 .mmd 源文件按模塊或文檔分目錄存放比如 diagrams 目錄放源文件docs/assets 放導出圖片讓源文件和產物互不混淆。這樣批量任務、CI 清理、文檔引用都有清晰的路徑。配置統一的導出腳本。把導出命令寫進項目的 package.json 或其他腳本文件避免每次手工敲一長串 mmdc 參數{ scripts: { diagrams: mkdir -p docs/assets for f in diagrams/*.mmd; do mmdc -i \$f\ -o \docs/assets/$(basename \${f%.mmd}\).svg\; done } }引入 CI 自動校驗。在提交或發布流程中跑一次 mmdc語法有問題直接構建失敗避免爛圖進入正式文檔。這一步相當于給流程圖加了一個語法檢查閘門效果非常明顯。固定 CLI 版本也很重要鎖住 mermaid-js/mermaid-cli 的版本避免更新后渲染效果變化導致文檔里的圖全部換樣。敏感信息處理要養成習慣。涉及架構、賬號、客戶數據的流程圖先過濾再渲染對外發布前檢查節點文本是否包含內部域名、IP、密鑰片段。自建渲染服務只允許內網訪問接口加請求體大小限制和超時設置避免被濫用。11. 總結與下一步這個項目思路最值得試的點是把流程圖從“畫布文件”變成“文本代碼”。有了這個前提版本管理、diff 評審、CI 生成、批量導出全部順理成章。你維護的是流程邏輯渲染交給 Mermaid不再需要回到 diagram editor 里手工重繪。建議先做三件事在 VS Code 里裝好預覽插件把一張現有流程圖改用 Mermaid 重寫用 mermaid-cli 跑通一次 SVG/PNG 導出把導出腳本寫進項目形成固定的文檔生成命令。最容易踩的坑有兩個。一是上來就畫超大圖布局不理想后覺得工具不行實際上是沒拆圖二是在線服務直接渲染敏感圖表造成信息泄露。這兩點規避掉剩下的就是熟悉語法。后續可以擴展的方向把 Mermaid 接入接口文檔平臺讓流程圖和接口定義同步更新用 CI 在每次代碼合并后自動刷新架構圖多團隊共建公共 .mmd 片段庫復用標準流程子圖。先把一條鏈路跑通再逐步放大這套工作流會越用越順。