企业官网建设流程全解析

做技术这一行，谁电脑里没堆着几张架构图、流程图、时序图？从给新人讲系统，到设计评审、周报同步、故障复盘，图表几乎是技术沟通的默认语言。但真正让我下决心整理一套可落地的图表设计工程化方案（也就是这个项目名 diagram-design 想表达的东西），是某次事故：团队里一份核心链路图同时存在三个人的电脑里，三个版本互相矛盾，线上出问题后谁都不敢打包票说哪张才是真实的。一张图都管不好，系统设计和文档沉淀自然无从谈起。

手动画图工具确实上手快，但图一旦多起来、改动频繁起来，版本混乱、样式不统一、没法纳入协作流程的问题就会集中爆发。diagram-design 的核心思路，是把图表当成代码来管理：文本化定义、模块化拆分、自动化渲染、全部纳入版本控制。这套方法既适合个人维护笔记和项目文档，也适合小团队一起维护设计文档。下面的内容会从需求拆解讲到完整落地，涉及工具选型、目录规范、核心绘制原则和典型避坑，想给文档和架构设计插上工程化翅膀的朋友，可以放心往下看。

1. 需求拆解：为什么需要一套图表设计规范

1.1 图表泛滥带来的技术债

大部分团队其实都经历过这样的过程：一开始大家用白板画图，讨论完拍照往群一甩，谁也没想着保存源文件。过段时间有人说要归档，就有人用绘图工具重新画一遍，画完再导成图片塞进文档。表面上图表数量不少，实际上处处是雷。

一个核心话题图散落在三四个地方，是家常便饭。白板照片里的原始版本、文档里重新绘制的版本、某个同事本地未提交的修改版，以及线上演示用的精简版，内容细节完全不同。有人加了缓存节点没人同步，有人改了接口没人更新连线，等到真正要拿去定位问题时，所有图都像古董，看着有历史感，实际信息全是错的。我把这种现象叫图表技术债：图不仅没有降低沟通成本，反而因为不一致制造了新的争议。

代码化图表天然能解决这个根因。它把图画变成纯文本描述，可以放进仓库里做版本管理。每次改动都能产生 diff，谁在什么时候改了哪个节点、删了哪条连线，全部有据可查。文档过期的问题也从根上被堵住：文本源文件改了，重新渲染一下就是新图，不存在"忘了改图片"这个状态。

有人会问，用绘图软件画完存个源文件不也能进版本库吗？可以，但本质上完全不一样。二进制源文件虽然也入库，但没法 diff，没法精准 merge，打开还需要特定软件。图表一旦多起来，文本文件完全可以像代码一样 review，而绘图软件的源文件基本只能一对一单人维护，协作能力差了不止一个量级。

1.2 代码化图表 vs 传统绘图工具

传统绘图工具和代码化图表并非谁完全替代谁的关系。我把两者的适用边界理了一下，供你按场景对照参考。

从这个表能看出，项目文档、架构设计、需长期维护的技术资产，选代码化；一次性的头脑风暴、临时讨论，用白板和绘图工具反而更快。我个人的切分标准很简单：这个图画完之后还要不要继续改？要改超过三次，就值得代码化。只画一次、下次重画也行，那用什么都无所谓。

一个容易忽略的点是样式一致性。传统绘图工具在团队里最大的问题是每个人画风不一样：有人喜欢圆角矩形，有人用直角，有人把所有节点都标成红色。代码化图表可以用统一主题文件约束颜色和字体，从机制上消除个人风格差异。这一点看似不起眼，实际是图表规范能否长期执行的关键。

2. 工具选型与方案确立

2.1 主流文本化图表工具对比

diagram-design 想落地，第一步是选一个称手的文本化图表引擎。市面常见的方案基本集中在四类：以简洁著称的 Mermaid、老牌的 PlantUML、布局算法强悍的 Graphviz，以及后起之秀 D2。我逐个用过，简单分享一下实际体感。

• Mermaid：Java生态开发者大概率不陌生，语法最贴近自然语言，graph 里用-->画箭头，sequence 里就是参与者之间发消息。它支持流程图、时序图、类图、状态图、甘特图等十几种类型，文档和示例都非常完善。对小团队和大多数业务系统建模来说，Mermaid 是最低摩擦的选择。

• PlantUML：和 Mermaid 定位接近，但思考框架更偏 UML。类图、用例图、时序图这些建模类型的表达力很全面，很多技术方案书里能看到它的身影。它的渲染依赖图形布局服务，首次使用需要本地配环境，比 Mermaid 稍微重一点。

• Graphviz：本身是一个布局引擎，通过 DOT 语言描述节点和边。它最强的点在于布局算法，上百个节点的大图交给它也能算出一个相对合理的结果。缺点也很明显，DOT 语法相对底层，画简单图也要写一堆属性和边声明，上手成本比前两者都高。适合超大拓扑结构，不适合日常快速画业务图。

• D2：新锐选手，语法设计很现代，布局引擎集群架构上有了新进展，官方提供的主题体系对设计感有追求的人很友好。生态还在快速建设中，插件和周边工具不如前几个丰富，生产环境大规模使用需要谨慎评估。

做选型的时候不要只看功能表，要看你团队里谁来维护这些图。一个只有架构师玩得转的强工具，不如一个全员都能看懂、偶尔能改两笔的工具更有长期生命力。我通常的建议是：业务架构和流程文档优先选 Mermaid，技术性较强的类图和状态建模可以考虑 PlantUML，图太大太复杂、超过单图合理承载上限时再上 Graphviz。项目初期不要同时引入两三种引擎，统一一种，等真的遇到瓶颈再补充，收益最大。

2.2 diagram-design 的目录结构与规范

工具确定后，下一步是定义项目里图表文件的组织方式。我实践的目录结构大致是这样的：

docs/ diagrams/ src/ system/ core-flow.mmd deploy-topo.mmd business/ order-flow.mmd refund-flow.mmd dist/ system/ core-flow.svg deploy-topo.svg business/ order-flow.svg refund-flow.svg styles/ default.mmd scripts/ render.mjs

这个结构看着简单，背后有几个关键约束：

src和dist严格分离。源文件只存在于src，渲染产物自动生成到dist。dist下的一切文件默认不手动编辑，就算被误删，重新跑一遍渲染脚本就能全部恢复。这个约定的意义在于，任何人接手后都不用理会产物目录，只管改源文件即可。

styles放主题文件。所有图共享一套颜色、字体、节点样式，而不是在每个源文件里各写各的。哪个业务域用什么颜色，有没有风险节点和废弃节点，统一在主题里定义。类似前端的 CSS 变量，把图表的视觉语言集中管理起来。

scripts放渲染脚本。脚本提供统一的渲染入口，比如render.mjs负责扫描src下所有源文件并输出到dist。我新增一张图的时候只需要往src放一个文件，脚本会自动处理剩余流程。这套目录规范本身不复杂，但它是整个方案的地基：没有它，代码化图表只是换了个画图方式；有了它，图表才真正变成文档体系的一部分。

3. 核心设计原则与实操

3.1 单一数据源：图表也要版本管理

强调多少遍都不为过：一个图只能有一个源文件，且一切衍生文件必须由这个源文件生成。很多团队拍板上 Mermaid，用着用着还是乱了，原因是有人直接把渲染好的 SVG 下载下来贴到别处去了，甚至直接在 SVG 上手动改了内容。流程图一脱离源文件，老问题就回来了。

单一数据源要求所有图表的展示场景都基于同一个源文件。文档里嵌入的图，由构建流程自动从源文件渲染生成；分享出去的图片，也是渲染产物再导出，绝不允许出现"这一版是手改的"这种状态。

实际操作中，我会把渲染命令固化成脚本，并建议设计走一遍完整流程再做补充：在文档中引用产物，而不是复制粘贴产物。文档每次构建时自动触发渲染，源文件有改动，产物图自然更新，不存在"我改了源文件但忘了重新导出"的中间态。

还有个容易忽略的细节：源文件入库，产物默认也入库，但从工程角度应该让 CI 来生成产物。最省事的处理是产物不入主分支，只作为构建产物在需要时生成。如果团队规模不大、又没有 CI 环境，可以妥协让产物入库，但必须在 README 写清楚来源和生成方式。妥协可以，遗忘源头绝不可以。

3.2 模块化拆分：怎么把大图变小图

架构图最容易犯的错误是想着一张图装下整个世界。我见过一张线上支付链路图，从客户端、网关、服务、数据库到外部渠道，密密麻麻摆了上百个节点。画的时候费劲，画完没人看得清，连放大都救不了，因为分支太多，视觉复杂度早就超出人类短时记忆的承受范围。

代码化图表提供了一套更好的思考方式。它鼓励你把大图拆成小图，再通过引用关系把它们组织起来。具体来说有三种拆法。

第一种按系统边界拆分。一个下单流程，不要在图上画出商家后台的所有模块，只画与下单直接相关的核心链路。其他的模块单独建一张管理端架构图，让两张图各自聚焦。判断界限就是边界：一张图只描述一件事。

第二种用子图分组。同一个流程中确实存在多个子系统时，用子图语法把它们框出来，视觉上一眼能看出哪些节点属于哪一方。子图本质上是分组，不改变图的结构，但对阅读体验的提升非常明显。

第三种跨图引用。业务上相关的两张图，在图的关联节点上标记链接，让读者能跳转到另一张图的对应节点。有人维护过大规模文档后会发现，跨图引用做得好，文档可以从任意一张图出发，顺着引用把整个系统都串起来，形成网状导航体验。

拆图的时机也值得注意。不是所有图都要拆，节点在二十个以内、关系一维线性的图，整体画出来反而更直观。但当节点数量逼近三五十个，或者出现网状交错时，立刻拆图。不要等到渲染出来发现连线条都叠成一团再动手，那时候重构成本已经很高了。

3.3 统一样式：让图不只是正确，还清楚

技术团队对图表的评判标准常常只停留在"对不对"，很少考虑"清不清楚"。实际上，图表的信息传达效率在很大程度上由样式决定。一张全图所有节点都是同一种颜色、同一种边框的架构图，逻辑上完全正确，但读图的人得靠逐个看文字才能区分模块边界，这基本等于没设计。

在 diagram-design 的实践里，我定义了一套语义化颜色规则：

• 基础设施层（数据库、中间件、第三方服务）用一种颜色，比如灰蓝色
• 核心业务模块用一种颜色，比如深绿色
• 风险组件或计划替换的模块用黄色标注
• 已废弃节点统一用红色划线，表示不可用

这套规则放在主题文件里，任何人画新图都从主题里取色，不允许自己随手挑一个看起来差不多的色号。你可能觉得这种限制有点死板，但真等你看到两份文档里"同一个服务"出现三种不同深浅的蓝色时，就会理解统一颜色到底有多重要。

除了颜色，节点的命名规范也要统一。每个节点必须有完整语义的名称，禁止使用node1、serviceA这类无意义标识。连线必须带动词化标签，比如"调用""订阅""写入"，而不是裸的一条箭头。不要小看这些细节，图表的可读性提升恰恰来自这里。真正专业的图表设计，是让正确性和清晰度同时达标，而这两者分开来看都不难，放在同一张图里做到平衡才是功力所在。

4. 完整实操流程：从空目录到自动化渲染

4.1 初始化项目结构

说了这么多原则，落到实操才是价值。我就按上面提到的目录结构，完整演示一遍从零开始建一套代码化图表流程的过程。

先创建目录骨架：

mkdir -p docs/diagrams/src/system \ mkdir -p docs/diagrams/src/business \ mkdir -p docs/diagrams/dist/system \ mkdir -p docs/diagrams/dist/business \ mkdir -p docs/diagrams/styles \ mkdir -p docs/diagrams/scripts

接着安装图表渲染工具。以 Mermaid 为例，推荐先把命令行接口装进局部环境：

cd docs/diagrams npm init -y npm install --save-dev @mermaid-js/mermaid-cli

局部安装的好处是版本可控。如果直接全局安装，不同项目的渲染版本一旦不一致，同一份源文件可能出现不同的渲染结果。对于图表这种要进版本管理的资产，可复现性比省一个安装步骤重要得多。

然后初始化主题文件，放在styles/default.mmd里。这个文件定义基础样式，比如节点填充色、字体、连线样式等，让后续所有图共享同一套排布。

4.2 编写第一张架构图

目录和主题就绪后，开始写源文件。以core-flow为例，它是系统主流程的架构图，源文件放在src/system/core-flow.mmd。内容只描述节点和连线，不重复写样式，任何颜色和字体都从主题继承。

graph LR A[用户入口] --> B{网关} B --> C[订单服务] B --> D[支付服务] C --> E[(数据库)] D --> F[外部渠道] classDef core fill:#e8f5e9,stroke:#2e7d32 classDef infra fill:#e3f2fd,stroke:#1565c0 class C,D core class E,F infra

这个示例里，用户入口指向网关，网关分流到订单服务和支付服务，订单服务访问数据库，支付服务调用外部渠道。classDef部分定义了两类节点的视觉归属，一类是核心业务模块，一类是基础设施。

编写时有一个很关键的习惯：每个子图都单独写一个文件，而不是在同一个文件里靠注释区分。这样后续改名、拆分、复用都更方便。同一张图内有多个子系统时，用子图语法在文件内分组。

写好源文件，先手动渲染一张看效果：

npx mmdc -i src/system/core-flow.mmd -o dist/system/core-flow.svg

这行命令读取源文件，输出 SVG 到产物目录。只要源文件没有语法错误，基本一次就能成功。

4.3 自动化渲染与文档集成

手动渲染只能解决单张图的问题，如果项目里已经有几十张图，靠手敲命令效率太低。真正让这套方案起飞的是批量脚本和文档构建流程。

脚本核心逻辑很简单：递归扫描src目录下所有.mmd文件，按相对路径映射到dist目录并逐个渲染。

find src -name "*.mmd" | while read -r file; do out="dist/$(dirname "$file" | sed 's|src/||')/$(basename "$file" .mmd).svg" mkdir -p "$(dirname "$out")" npx mmdc -i "$file" -o "$out" done

这段脚本跑一遍，所有源文件就会全部更新到产物。稍有规模的项目，建议把这条命令固化成 npm script，比如npm run diagrams，团队其他人不用记命令，直接执行就行。

再进一步可以接入 CI。每次检测到src目录下的图表源文件变更，CI 自动重新渲染，并把产物推到文档站点或制品库。这样团队成员提交代码时，只要改了源文件，文档站上的图表会自动同步更新，彻底消灭"文档图和代码不一致"的顽疾。

我更推荐团队用文档整合方案，像 MkDocs、VitePress 这类支持运行时渲染的文档框架都可以在 Markdown 中直接嵌入图表源码，构建站点时再统一渲染。如果选这条路，dist目录甚至可以不入库，交给文档构建流程动态生成。这套做法的体验极其顺滑，也是目前我认为最接近"图表即代码"理念的落地形态。

5. 常见问题与排查指南

5.1 渲染失败排查

文本化图表最常遇到的问题就是渲染失败。新手能看到的通常只有一句冷冰冰的语法错误提示，第一次遇到很容易懵。结合我的经验，常见的就三类。

语法错误。Mermaid 对缩进不敏感，但对接线标注、闭合符号非常敏感。箭头写成了两个连字符多一横，或者子图没有配对齐的结束关键字，渲染就会失败。排查最快的办法是先把内容精简到只剩一个节点一条连线，逐步加回元素，定位出错的具体位置。

中文乱码或字体问题。有些渲染环境默认字体不含中文字形，输出图片里中文变成方块。之前遇到过 CI 环境渲染出的 SVG 在本地正常、在站点上乱码的情况，排查半天发现是服务器缺少中文字体包。本地安装对应字体，或者在主题里显式指定一个支持中文的字体族即可解决。

版本漂移。不同版本的渲染引擎语法兼容性并不完全一致，新版本可能废弃旧写法、也可能改变某些关键字的解析行为。同一个源文件在不同环境渲染得一模一样，这是工程要求。解决方式很简单，把渲染工具版本锁定，通过 lock 文件保持环境一致，升级时单独走一次全量渲染验证，绝不在生产文档流程中静默升级。

5.2 大图性能与可读性

当图里节点数超过一百，即使代码化也未必能解决一切，因为布局引擎的算力有限。这里最容易踩的坑是在一张图里塞过多节点后强行调整布局参数，指望数字好看一些。我的实践认知是：渲染性能和可读性的瓶颈常常不是工具，而是图本身的结构。一张图超过百个节点，先回到第 3.2 节的模块化拆分原则，把图按边界切开，再考虑布局优化。

如果确实需要展示一张包含几百个节点的全局拓扑图，那 Graphviz 这类专门的布局引擎可能更合适，它会用力导向算法计算节点位置，处理大规模节点通常比 Mermaid 的默认布局表现好。不过全局拓扑图的阅读体验依然有限，所以我的建议是：这种大图只作为全局概览，配合可点击跳转的小图共同使用。大图负责给人"全貌感"，小图负责具体信息入口，不可偏废。

5.3 协作中的冲突与约定

代码化图表进入多人协作场景后，最常见的冲突就是两个人同时改同一个源文件。文本文件虽然能进版本库 diff，但多人同时编辑时，不同分支合并依然会产生冲突。分布式系统里养成一次只改一张图的习惯，比反复消解合并冲突划算得多。

为了降低冲突频率，有两点值得推广。一是粒度拆分：把大图拆成小图之后，每个人维护自己责任范围的那几张，合作同时改同一张图的概率自然下降。二是变更前通知：如果有改动计划，先看一眼这份文件最近有没有被别人动过，主动和协作对象打个招呼。这些老套但有效的配合方式，在图表协作上也同样适用。

另外一个容易被人忽略的问题是 PR review。图表源文件的 review 通常不被重视，很多人觉得"图能渲染出来就行"。但实际上图表的 review 尤其重要，因为节点命名、连线方向、边界划分是否合理，直接反映了对系统的理解。一旦变化涉及核心链路，review 应该像 review 代码一样严格，宁可多问几个为什么，也不要让错误的架构图在文档里躺几个月。

最后说点个人经验

diagram-design 走到今天，对我最大的改变不是工具链升级，而是看待图表的方式。以前画完一张图就觉得任务完成，现在我会下意识地问：这张图有人维护吗？它会在哪里被引用？源文件是否入库？如果一个图没有对应的源文件，没有明确的维护路径，我宁愿先不画，等真正需要归档时再动手。

如果你正准备开始整改团队的图表管理，我给的建议是不要一上来就追求全量迁移。先挑一张反复改动的核心图，把它代码化，接进文档构建流程，跑通整个链路；等团队习惯了这种工作方式，再把其他图逐步迁移过来。一个能不断更新、持续有效的图表工作流，比一堆画得漂亮但无人维护的图值钱得多。

真正画出好的架构图，靠的从来不是某个高级工具的加持，而是清晰的思考和数据管理习惯。diagram-design 给我最大的收获，简单说就是：把图当代码对待，让每一张图都成为不断演进的资产，而不是一次性的摆设。至于怎么选择、怎么做，上面都写透了，剩下的就是动手试。