3.2 用内联 SVG 画架构图
3.2 用内联 SVG 画架构图
SVG 是写在围栏里的一段矢量图形描述代码，围栏语言标注写 svg。Mermaid 擅长"节点加箭头"的固定范式，但分层架构图、多维对比矩阵、标注示意图需要自由布局——图层怎么摆、标注指向哪、颜色分区多大，都由你说了算。这就是 SVG 的领地。
一个最小可用的 SVG 块
渲染成一张浅蓝圆角卡片。拆解要素：
viewBox="0 0 400 160"：声明画布坐标系，渲染器据此定视口——必写。<rect>画矩形（rx是圆角）、<text>写字、<line>画线、<path>画任意路径。- 文字要带
font-family中文字体回退，否则某些渲染环境显示方块。 fill填充色、stroke描边色，用十六进制或色名。
什么时候该用 SVG 而不是 Mermaid
我的判断清单，命中任意一条就上 SVG：
- 需要分层分区的架构图——上下叠的层次、包住多组件的大框。
- 需要对位比较的矩阵或速查图。
- 需要标注指向：箭头、序号、说明文字精确落在某处。
- 同一份图要在多个文档复用、且希望它像代码一样可 diff。
反过来，纯"节点连节点"的图交给 Mermaid 更省事——SVG 每个坐标都要手调，成本不可忽视。
实战：画一张三层架构图
这张图的信息组织方式 Mermaid 做不到：三个色带明确分层、每层内组件横向并列、层间只有两根干净的竖线表达调用方向。画这类图的步骤我总结为"先分区、再摆件、后连线、最后标注"：先用大色块把层次占住，再往每层里放小卡片，连线能省则省（层间一根线胜过组件间十根线），最后加序号或说明。
⚠️ 常见坑：SVG 块写完必须经过平台的渲染流程转成图片，否则读者看到的是一坨源码。写作时给它配一个三级标题当图名（渲染后成为图片的替代文本），也是必备习惯——本教程里的每张 SVG 都带图题。
实战：画一张两方案对比矩阵
条形长短直接编码优势大小——这种"长度即数据"的矩阵，表格做不到（只有文字），Mermaid 也做不到（没有范式），正是 SVG 的招牌能力。
先画草格子：SVG 的坐标规划法
SVG 手写最大的心理门槛是"满屏坐标"，破解办法是把布局问题变成算术问题：先在等宽字体里画一张字符草稿，把画布划成网格，坐标就不用试错了。以三层架构图为例，先用文本把格子定下来：
画布 800 x 360，行高 120，左右边距 40 行一 y=20 ～ 140 接入层：网关、负载均衡 行二 y=160 ～ 280 服务层：订单服务、库存服务、用户服务 行三 y=300 ～ 360? → 放不下，画布加高到 460 列宽 服务层三列：x=40/280/520，每卡宽 200
草稿阶段就把两类低级错误消灭在字符世界里：画布高度不够（第三行放不下）、卡片重叠（列宽没减间距）。规划完成后，坐标全部来自简单加法——这是手写 SVG 能保持可维护的关键：别人读你的 SVG 源码时，看到的不是一堆魔法数字，而是 40、280、520 这样一望即知的网格节奏。
另一条提效经验是把常用件做成"积木段"集中复用。卡片（圆角矩形加居中文字）在一张图里往往出现五六次，把它写成一个固定结构、只改坐标与文字，视觉自然统一：
积木：卡片 <rect x="X" y="Y" width="200" height="70" rx="8" fill="#EEF2FF" stroke="#4F46E5"/> <text x="X+100" y="Y+42" text-anchor="middle" font-size="15">卡片名</text> 约束：卡片文字一律居中(text-anchor=middle)，字号 15， 描边色统一取层主色，宽高全网格一致
团队协作里这份"积木约定"价值更大：多人的图出自同一套积木，全库文档的图形风格才不会各自为政。改版时也只改积木定义里的颜色与字号，逐图替换即可——SVG 是代码这句话的完整含义，包括它也该享受代码的复用纪律。
本节要点回顾
- svg 围栏 + viewBox + 中文字体回退，三件套缺一不可。
- 选型判据：分层、对位、精确标注、可 diff——命中就上 SVG。
- 作图四步：先分区、再摆件、后连线、最后标注。
- 图必须配图题（三级标题），并确保走了平台的渲染流程。
一张架构图的完整走查
把作图四步落在一张真实的分层架构图上。第一步分区：画布 viewBox 定为 0 0 640 360，纵向分三层——接入层 y 40-120、服务层 y 140-240、数据层 y 260-330，各层用半透明底色矩形占位并配层名。第二步摆件：每层两个到三个矩形代表组件，同层组件等宽（120 像素）、等距（40 像素），文字水平垂直居中。第三步连线：用直线或折线连接层间组件，箭头统一放终点，跨层跳线走层间空隙而不是压在组件上。第四步标注：连线中点放标签（协议名、数据量），画布底部留图例区说明线型含义。走查的关键体会是：前三步做完时图已经"成立"，第四步只是补盲文——顺序颠倒（先画线再摆件）是新手图歪斜的根源。
坐标计算不必手算精到位，两个技巧能省一半时间：组件宽度统一后，x 坐标就是一个等差数列（40, 200, 360...）；层高统一后 y 坐标同理。改图时也只动这两个数列，结构不变。真正的克制在配色：一张图至多三种颜色——底色一种、组件描边一种、强调（危险路径、核心链路）一种。彩色缤纷的架构图看似专业，实则每个颜色都在喊叫，读者反而抓不住那条真正该看的路径。
复用与版本：把 SVG 当资产管理
SVG 源码写在文档里虽好，一张图被三篇文档引用时就出现三份拷贝——拷贝即分叉，改一处漏两处。治理办法是图库模式：所有 SVG 集中存放在 images 或 assets 目录，文档内以图片语法引用（多数平台对 .svg 文件按图片渲染，效果与内联几乎一致），需要被 Mermaid 化改造的例外才内联。图库模式下每张图配文件名规范（arch-分层-202608.svg 带日期或版本），图与文档的引用关系靠链接检查工具守护。这套管理的核心仍是那条老原则：图是资产，资产要有唯一权威版本——内联的便利只属于一次性的小图，一旦复用就升级为资产，按资产管理。