企业官网建设流程全解析

1. 从一张草图到一套系统：diagram-design 到底在解决什么问题

第一次看到 “diagram-design” 这个标题，很多人会以为它只是教你怎么画图——选个模板、拖几个框、连几条线，导出 PNG 就完事了。但真正在项目里反复画过架构图、流程图、时序图的人都知道，画图本身从来不是难点，难的是让图“活”起来：需求一变，图就得跟着改；团队里五个人画同一套系统，能画出五种风格；今天用这个工具，明天换那个平台，历史图源文件找都找不回来。

diagram-design 这个项目，核心就是冲着这些痛点去的。它不是一个单纯的绘图工具推荐合集，而是一套从设计规范、工具选型、图源管理到自动化生成的完整方法论。说得直白一点，它要解决的是：怎么让一个团队在三个月、半年甚至更长时间跨度里，持续产出风格统一、信息准确、可维护可追溯的图表资产。

这套东西适合谁？我梳理了一下，大概三类人最用得上。第一类是技术团队的架构师或 Tech Lead，需要频繁输出系统架构图、部署图、数据流图，而且这些图要跟着代码一起迭代。第二类是产品经理和项目管理者，流程图、状态机、泳道图是日常刚需，但又不希望每次改需求都从头画一遍。第三类是独立开发者或小团队，没有专职设计师，但又想让对外文档里的图看起来专业、不寒碜。

我自己在过去几年里，先后在三个不同规模的项目里折腾过图表设计这件事。从最早用在线工具随手画，到后来尝试用代码生成图表，再到最后沉淀出一套自己的 diagram-design 流程，踩过的坑可以说能写满一个笔记本。这篇文章就把这套东西完整拆开，从思路、工具、实操到避坑，一次性讲透。

2. 整体设计思路：为什么“图”也需要设计系统

2.1 图表混乱的根源不在工具，在缺少约束

大部分人遇到图表问题，第一反应是“换个更好的工具”。但换工具解决不了根本问题。我见过一个团队，三个月内换了四款绘图工具，结果图还是乱——因为乱的根源不是工具能力不够，而是没有统一的约束规则。

具体来说，图表混乱通常表现为这几种：颜色随意，同一种含义的模块在不同图里颜色不一样；字体大小不统一，有的图标题 14px，有的 20px；连线风格五花八门，有的直角有的曲线有的带箭头有的不带；命名不规范，同一个服务在不同图里叫不同名字。这些问题单独看都是小事，但积累起来，一套图放在一起就像拼凑出来的，专业感直接归零。

diagram-design 的第一个核心思路就是：先定规范，再选工具。规范包括颜色语义、字体层级、图形元素标准、命名规则、布局栅格。这些东西定下来之后，不管用什么工具，产出的图都能保持一致性。

2.2 图源即代码：让图表可版本化、可追溯

第二个核心思路是图源文件必须可版本化。什么意思？就是你的图不能只存在于某个在线平台的服务器上，必须以文本形式存在你的代码仓库里。这样每次修改都有 commit 记录，能 diff、能回滚、能协作。

这就引出了 diagram-design 里最关键的一个选型决策：优先选择支持文本描述生成图表的方案。比如用 Mermaid、PlantUML、Graphviz 这类工具，图的内容用代码描述，渲染出来的图只是产物。这样做的好处太多了：改一个服务名，全局搜索替换就行；想调整布局，改几行代码重新渲染；多人协作时，Git 合并冲突比二进制文件好处理得多。

当然，纯文本方案也有局限，比如复杂的手绘风格图、高度定制化的视觉设计，还是得用传统工具。所以 diagram-design 的思路不是“一刀切”，而是分层处理：标准化程度高的图（架构图、流程图、时序图）用代码生成；需要精细视觉控制的图（宣传物料、UI 稿）用设计工具；两者之间通过统一的规范来衔接。

2.3 自动化嵌入：让图跟着文档一起更新

第三个思路是图表要能自动嵌入到文档和代码仓库中。我见过太多项目，README 里的架构图还是两年前的版本，早就跟实际系统对不上了。原因很简单：更新图太麻烦，要打开工具、改图、导出、替换文件、提交，一套流程下来十几分钟，谁愿意天天干？

diagram-design 的做法是，把图表生成集成到 CI/CD 流程里。图源文件改了，自动触发渲染，生成的图片自动更新到文档目录。这样图就永远不会过期，因为它跟代码一样，是构建流程的一部分。

3. 核心细节解析：规范、工具与图源管理

3.1 颜色语义系统：让每种颜色都有明确含义

颜色是图表设计里最容易被忽视、也最容易出问题的部分。我的建议是，先定义一套语义色板，而不是先选好看的颜色。

具体怎么做？先列出你的图表里需要区分的元素类型。比如架构图里通常有：前端服务、后端服务、数据库、缓存、消息队列、外部依赖。然后给每一类分配一个颜色。注意，颜色数量控制在 6 到 8 种以内，太多了反而分不清。

这套色板定下来之后，所有图都严格遵守。新人画图时直接查表，不需要自己发挥。时间长了，团队里所有人看到蓝色就知道是前端，看到橙色就知道是存储，信息传递效率会高很多。

注意：色板要同时考虑浅色和深色背景下的可读性。我一般会选饱和度中等、明度适中的颜色，避免太亮或太暗。

3.2 字体与布局栅格：细节决定专业度

字体这块，我的经验是最多用两个字号层级：标题用一个字号，正文/标签用另一个。字号差距控制在 1.5 倍左右。比如标题 18px，标签 12px。不要搞出四五个字号层级，那样看起来会很乱。

布局栅格方面，如果是用代码生成图表，大部分工具会自动处理布局，你只需要控制节点之间的间距参数。如果是手动绘图，建议用 8px 或 10px 的栅格系统，所有元素的位置和大小都对齐到栅格上。这样出来的图会有一种“整齐感”，虽然说不清为什么，但看起来就是舒服。

3.3 工具选型：什么场景用什么工具

工具选型是 diagram-design 里最实操的部分。我按场景列一下我的推荐：

代码生成类图表（架构图、流程图、时序图、状态图）：

• Mermaid：语法简单，GitHub、GitLab、Notion 原生支持，适合快速上手
• PlantUML：功能更强大，支持更多图类型，适合复杂场景
• Graphviz：布局算法强，适合关系复杂的网络图

手动绘制类图表（UI 稿、宣传图、高度定制化视觉）：

• Excalidraw：手绘风格，适合快速草图和白板讨论
• Figma：专业设计工具，适合需要精细控制的场景
• draw.io：免费，功能够用，适合中小团队

混合方案：

• 用代码生成基础结构，导出 SVG 后在设计工具里微调
• 用设计工具做好模板，代码生成时套用模板样式

选型的核心原则是：标准化程度越高的图，越应该用代码生成；视觉要求越高的图，越应该用设计工具。不要试图用一个工具解决所有问题。

3.4 图源文件管理：目录结构与命名规范

图源文件的管理，我建议在项目根目录下建一个docs/diagrams目录，里面按类型分子目录：

docs/diagrams/ ├── architecture/ │ ├── system-overview.mmd │ ├── deployment.mmd │ └──>{ "frontend": "#4A90D9", "backend": "#27AE60", "storage": "#E67E22", "cache": "#8E44AD", "queue": "#E74C3C", "external": "#95A5A6" }

style.css用来定义 Mermaid 或 PlantUML 的样式覆盖：

.node.frontend { fill: #4A90D9; stroke: #2C6FB5; } .node.backend { fill: #27AE60; stroke: #1E8449; } .node.storage { fill: #E67E22; stroke: #B85C1A; }

这些文件的作用是让所有图共享同一套视觉规则。改一个颜色，所有图重新渲染后都会跟着变。

4.2 第二步：配置渲染工具链

如果你用 Mermaid，最省事的方案是装一个 CLI 工具，比如@mermaid-js/mermaid-cli。安装命令：

npm install -g @mermaid-js/mermaid-cli

然后写一个简单的构建脚本build-diagrams.sh：

#!/bin/bash for file in docs/diagrams/**/*.mmd; do output="${file%.mmd}.svg" mmdc -i "$file" -o "$output" -c docs/diagrams/assets/mermaid-config.json done

这个脚本会遍历所有.mmd文件，渲染成 SVG，并且应用统一的配置文件。配置文件里可以指定主题、字体、颜色等参数。

如果你用 PlantUML，需要先装 Java 环境，然后下载plantuml.jar，渲染命令是：

java -jar plantuml.jar -tsvg docs/diagrams/**/*.puml

4.3 第三步：集成到 CI/CD

在 GitHub Actions 或 GitLab CI 里加一个 job，每次 push 到主分支时自动渲染图表：

name: Build Diagrams on: push: paths: - 'docs/diagrams/**' jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: '18' - run: npm install -g @mermaid-js/mermaid-cli - run: bash build-diagrams.sh - uses: actions/upload-artifact@v3 with: name: diagrams path: docs/diagrams/**/*.svg

这样每次图源文件有改动，CI 会自动渲染并上传产物。如果配合静态站点生成器，还可以直接把渲染好的图部署到文档站点上。

4.4 第四步：写第一个图源文件

拿一个典型的系统架构图举例，Mermaid 的写法：

graph TD A[Web前端] --> B[API网关] B --> C[用户服务] B --> D[订单服务] C --> E[(用户数据库)] D --> F[(订单数据库)] D --> G[消息队列] G --> H[通知服务]

渲染出来就是一张清晰的架构图。改起来也方便，比如要把“用户服务”改成“账户服务”，直接改一行文本就行，不用打开任何图形界面。

4.5 第五步：建立评审与更新机制

图源文件跟代码一样，需要评审。我的做法是，在 PR 模板里加一条检查项：如果改动了系统结构，必须同步更新对应的图源文件。评审时重点看三点：图的语义是否准确、命名是否规范、颜色是否符合色板。

更新机制方面，我建议每个月做一次“图表巡检”，把所有图过一遍，看看有没有过期的、命名不规范的、颜色跑偏的。这个工作看起来琐碎，但坚持下来，图表资产的质量会一直保持在高位。

5. 常见问题与排查技巧实录

5.1 渲染出来的图跟预期不一样怎么办

这是最常见的问题。Mermaid 和 PlantUML 的自动布局有时候会出人意料，比如节点顺序不对、连线交叉太多、分组框位置奇怪。我的排查思路是：

第一，检查节点定义顺序。大部分布局引擎会按照定义顺序来排布节点，调整顺序往往能改善布局。第二，用子图（subgraph）来强制分组，把相关节点放在一起。第三，如果还是不行，考虑换布局方向，比如从TD（从上到下）改成LR（从左到右）。

实操心得：Mermaid 的布局调整空间有限，如果对布局要求很高，建议用 Graphviz 或手动调整 SVG。

5.2 中文字体显示异常

用 Mermaid CLI 渲染时，如果系统没有安装中文字体，出来的图里中文会变成方块。解决办法是在配置文件里指定一个系统中已有的中文字体：

{ "themeVariables": { "fontFamily": "Noto Sans CJK SC, sans-serif" } }

如果服务器上没有中文字体，需要先安装，比如在 Ubuntu 上：

apt-get install -y fonts-noto-cjk

5.3 图源文件冲突怎么处理

多人协作时，如果两个人同时改了同一个图源文件，Git 合并时可能会冲突。因为图源是文本，冲突其实比二进制文件好处理。我的建议是：

• 尽量把大图拆成小图，减少冲突概率
• 冲突时不要慌，打开文件看冲突标记，手动合并
• 合并后一定要重新渲染，确认图没问题

5.4 常见问题速查表

5.5 独家避坑技巧

第一个技巧：图源文件里不要写死颜色值。把颜色定义在配置文件里，图源文件只引用语义名称。这样换色板的时候只需要改一个地方。

第二个技巧：给每个图源文件加一个头部注释，写明图的用途、最后更新日期、负责人。时间长了，这些信息比图本身还重要。

第三个技巧：导出 SVG 而不是 PNG。SVG 是矢量图，放大不糊，而且文件更小，还能用 CSS 控制样式。如果文档平台不支持 SVG，再考虑导出 PNG。

第四个技巧：定期清理废弃的图源文件。项目迭代过程中，总有一些图不再需要了。如果不清理，目录会越来越乱，新人根本分不清哪些是有效的。

6. 进阶玩法：让图表自动跟着代码走

6.1 从代码注释生成图表

如果你的项目用 TypeScript 或 Java，可以写一个脚本，从代码里的装饰器或注释中提取服务依赖关系，自动生成架构图。比如在服务类上加一个@DependsOn注解，脚本扫描所有注解，生成 Mermaid 图源，再渲染成图。这样图就永远跟代码一致，不需要手动维护。

6.2 用 API 文档生成时序图

如果你的项目有 OpenAPI 或 Swagger 文档，可以写一个转换脚本，把 API 调用链转成时序图。比如用户登录流程，从 API 文档里提取请求路径、参数、响应，自动生成时序图。这个方案特别适合微服务架构，因为服务间调用关系复杂，手动画图根本跟不上变化。

6.3 图表即文档：嵌入到静态站点

把渲染好的 SVG 嵌入到 Docusaurus、VuePress 或 MkDocs 里，配合搜索功能，图表就变成了可检索的文档资产。用户搜“订单流程”，直接就能找到对应的流程图，比翻文档快多了。

6.4 版本对比：让图表变更可追溯

因为图源是文本，你可以用git diff来看图的变化。比如两个版本之间，架构图多了哪个服务、少了哪个依赖，一目了然。这个能力在复盘和审计时特别有用。

7. 我在这套流程里踩过的坑

第一个坑是过度追求自动化。一开始我想把所有图都用代码生成，结果发现有些图（比如带复杂视觉设计的宣传图）用代码写简直是折磨。后来想明白了，自动化是为了效率，不是为了自动化本身。该手动的时候就得手动。

第二个坑是规范定得太细。最开始我定了一套非常详细的规范，颜色有十几种，字号有五个层级，结果没人遵守。后来简化到六种颜色、两个字号，反而大家都愿意用了。规范这东西，够用就好，太复杂等于没有。

第三个坑是忘了考虑渲染性能。图源文件多了之后，每次 CI 渲染要跑好几分钟。后来加了缓存机制，只渲染有改动的文件，时间降到了几十秒。

第四个坑是没有及时清理废弃图源。项目跑了一年多，docs/diagrams目录里堆了几十个文件，一半是废弃的。后来花了一个下午清理，顺便加了一个废弃标记规范，才算把这个问题解决掉。

这套 diagram-design 流程，我从最开始的手忙脚乱，到现在基本可以做到“改代码的同时顺手改图”，中间经历了大概半年的迭代。现在回头看，最大的收获不是学会了某个工具，而是建立了一种把图当作代码资产来管理的思维方式。图不再是附属品，而是跟代码一样，有规范、有版本、有评审、有生命周期。这个转变，才是 diagram-design 真正的价值所在。