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