企业官网建设流程全解析

有些吐槽比一次工具更新更能说明问题。比如这句调侃：现在用“open code”风格的自主开源创作集体做出来的项目，一眼看过去，功能是什么还不一定清楚，但 Mermaid 图倒是先铺满 README，而且渲染风格高度相似，统一到让人怀疑是同一个模板生成。这句话听起来像段子，但它确实点中了当前 OSS 协作方式里的一个真实变化：AI 参与生成代码和文档之后，Mermaid 图表成了“自动文档”的默认可视化语言，而风格配置却被很多人忽略了。

本文不打算讨论某个具体人物的原话，而是把这类调侃当成一个现象拆开看：为什么自主开源项目总是在用 Mermaid？为什么渲染风格总是那么像？想摆脱“一眼 AI 文档”的观感，应该从哪些层面去调整？更重要的是，在团队协作、自动生成、批量渲染这些真实场景里，Mermaid 的样式配置到底应该怎么做才不算踩坑。读完这篇，你会得到一套能够直接放进自己开源项目里的 Mermaid 风格管理思路。

1. 核心能力速览

这份表格里的内容不是某一个能双击启动的软件。它更像是一套方法论和配置实践的组合。如果你想在自己的自动 OSS 项目里让 Mermaid 图的风格稳定、不脏、可维护，可以直接跳去第 4 节和第 5 节，那里给出了可行的配置方案和批量导出路径。

2. 适用场景与使用边界

2.1 合适的使用场景

自主 OSS 项目，也就是大量使用 AI 辅助完成代码生成、文档撰写、代码评审的开源协作模式，目前最常见的输出物除了代码文件，还有两类东西：变更说明和架构图示。Mermaid 在这两类内容里都非常合适，因为它直接用文本描述图形，不需要单独维护一张图片文件，也和 Git 的 diff 流程天然兼容。代码评审的时候，如果 PR 里附的不是图片，而是一段可追踪的 Mermaid 文本，审阅者可以直接看出改动是否破坏了原有的模块关系，也可以很快速地在线编辑。

另一种适合的场景是文档站点的自动化更新。VitePress、Docusaurus、MkDocs 这类文档生成工具都内置了 Mermaid 或可以通过插件接入。每当主分支有新代码合并，流水线重新构建一次文档，Mermaid 图会自动重新渲染，不会像传统图片那样因为忘更新截图而失真。

2.2 需要谨慎的场景

也不是所有图都适合用 Mermaid。当系统模块特别多、信息层级特别深的时候，Mermaid 的布局算法有时候会生成一张行数很多、节点位置难以人工控制的“大长图”。这种场景更适合先用思维导图工具或者绘图软件做整体规划，再手工整理成几个粒度更小的 Mermaid 图。

另一个需要谨慎的地方是风格使用的边界。在一些正式对外发布的商业产品或政府采购项目中，架构图的颜色、字体、排版通常要遵循公司的品牌规范。如果直接把某个开源模板里的蓝色主题拿过来用，可能无意中违反视觉规范。建议在接入文档流程之前，先和设计或品牌团队确认一套可用的配色变量。

2.3 版权与合规提醒

如果 Mermaid 图所表达的信息来自代码结构、数据库表结构或内部业务流程，发布到公开仓库前要确认这些信息不涉及商业机密。自动生成文档的时候，AI 工具可能会把项目里的敏感字段名或内部 IP 直接写进节点文字里。这不是 Mermaid 本身的安全问题，而是整个自动文档流程都需要把关的环节。使用第三方渲染服务时，也建议不要把私有不公开的代码片段粘贴到在线编辑器里验证。比较稳妥的做法是用本地命令行工具渲染，或者把服务部署在内网环境。

3. Mermaid 渲染风格的核心概念

3.1 没有显式配置时，到底会发生什么

大多数人在 Markdown 里写 Mermaid 图是这么写的：

flowchart LR A[收集需求] --> B[代码生成] B --> C[代码评审] C --> D{是否通过} D -->|是| E[合并主分支] D -->|否| B

如果什么都不配置，不同的渲染器会返回不同的结果。GitHub 的 Markdown 渲染器有一套自己的默认主题，VitePress 插件会用另一套默认主题，Mermaid Live Editor 又会根据页面主题自动切换。也就是说，同一段 Mermaid 文本在不同平台上得到的视觉风格并不一致。对于一个以 Mermaid 为主要文档图表的开源项目来说，这其实是很大的不稳定因素。

“渲染风格”因此不只是审美问题，它本质上是一个一致性问题。项目的参与者可能在 GitHub 上看到一张效果图，又在本地 IDE 里看到另一张效果图，导致讨论时出现认知偏差。为了消除这种偏差，我们需要在 Mermaid 配置层面做统一。

3.2 Mermaid 主题体系

Mermaid 官方提供了几种内置主题：default、base、dark、neutral、forest。default 是经典浅色主题，最常见，也是网上大量自动生成文档的默认选择。dark 适合深色背景的演示文稿。neutral 的颜色饱和度比较低，看起来更克制。forest 的绿色系更强一些。base 最特殊，它通常被当作自定义主题的起点，配合 themeVariables 可以精细地定义大量颜色、边框、字体和背景变量。

注意，主题不能简单理解成“换皮”。不同主题对流程图节点、连线、标签、边距的处理都会有差异。真正可控的自定义方式是使用 base 主题，然后覆盖 themeVariables。

3.3 三种配置入口

第一种是最简单的，直接在 Mermaid 图代码块顶部加一行 init 指令：

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f0f4ff"}}}%% flowchart LR A[生成代码] --> B{自动评审}

第二种是通过文档站点的初始化脚本统一配置。以 VitePress 或者 Docusaurus 为例，可以在站点初始化 JavaScript 时调用 mermaid.initialize()，把配置对象传进去。这种方式适合全站所有 Mermaid 图默认都使用同一套风格。

第三种是用 mermaid-cli 在导出图片或 PDF 时传入配置文件。这种方式的优点是不需要修改 Mermaid 文本本身，适合批量处理遗留的 Markdown 文件。

4. 给自主 OSS 项目定制一套 Mermaid 风格配置

4.1 先想清楚风格要传达什么

很多“自主 OSS 创作集体”只花时间在功能生成上，很少有人认真思考文档的可视化语言。默认情况下，AI 生成的 Mermaid 图往往带着高饱和度的蓝色，节点文字是黑色，连线是深灰色。这种组合本身没有错，但当几十个开源项目都生成同一种风格时，用户的认知就会变得疲劳。

定制风格之前，最好先定三个方向：文档底色是浅色还是深色；品牌色或强调色是什么；图的用途是偏内部技术设计还是对外展示。只要确定了这三项，themeVariables 的填写就有了依据。

4.2 配置实例：让流程图不那么“模板脸”

假设我们要为一套面向开发者的开源协作工具设计浅色主题，强调色使用偏冷静的青蓝色，字体需要兼顾中文场景，那么可以这样定义基础配置：

{ "theme": "base", "themeVariables": { "fontFamily": "Inter, 'PingFang SC', 'Microsoft YaHei', sans-serif", "primaryColor": "#eef4ff", "primaryTextColor": "#1e293b", "primaryBorderColor": "#3361cc", "primaryBorderHoverColor": "#2547a0", "lineColor": "#7393c4", "textColor": "#1e293b", "clusterBkg": "#f8fafc", "clusterBorder": "#cbd5e1", "edgeLabelBackground": "#ffffff", "nodeBorder": "#3361cc", "nodeTextColor": "#0f172a" }, "flowchart": { "nodeSpacing": 45, "rankSpacing": 55, "curve": "basis", "htmlLabels": true } }

把这段 JSON 保存为 mermaid-theme.json。因为 Mermaid 的配置项在不同版本里会有少量差异，实际使用前建议先跑一次渲染确认变量名有效。如果你只想要“比默认好看一点”的效果，不用全部照抄，重点调整 primaryColor、lineColor 和 edgeLabelBackground 三个值就够了。

4.3 在单个 Mermaid 图里使用配置

把上面的 JSON 压缩成一行放进 init 指令里，就可以在单个 Markdown 文件中生效。注意引号要使用双引号，JSON 格式不能有尾逗号。

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#eef4ff", "primaryTextColor": "#1e293b", "primaryBorderColor": "#3361cc", "lineColor": "#7393c4", "edgeLabelBackground": "#ffffff"}}}%% flowchart TB A[开发分支] --> B[自动构建] B --> C{测试是否通过} C -->|通过| D[生成变更说明] C -->|失败| E[回滚]

渲染之后，节点会变成浅蓝色底、深色文字，连线会变成偏灰的青蓝色，整体观感会比默认主题干净一些。如果你的项目文档很多，不建议在每个文件里复制这行 init，太容易只改一处漏掉另一处。更推荐的方式是交给文档站点全局初始化。

4.4 全局初始化配置示例

在前端项目里，可以创建一个 mermaid-init.js 文件：

import mermaid from 'mermaid'; const defaultMermaidConfig = { startOnLoad: true, theme: 'base', themeVariables: { fontFamily: "Inter, 'PingFang SC', 'Microsoft YaHei', sans-serif", primaryColor: '#eef4ff', primaryTextColor: '#1e293b', primaryBorderColor: '#3361cc', lineColor: '#7393c4', edgeLabelBackground: '#ffffff', textColor: '#1e293b' }, flowchart: { useMaxWidth: true, htmlLabels: true, curve: 'basis' } }; try { mermaid.initialize(defaultMermaidConfig); } catch (e) { console.error('Mermaid initialize failed:', e); }

这样操作之后，同一个站点里所有没有显式写配置的 Mermaid 图都会按这套风格渲染。显式写在 init 指令里的配置优先级更高，可以覆盖全局配置。全局配置适合保证整体一致性，单图配置适合做局部例外。

5. 把 Mermaid 风格接入文档渲染流程

5.1 从一对一渲染到流水线渲染

个人写文档时，可以在本地通过 Mermaid Live Editor 查看效果。项目级文档不行，因为几十个 Markdown 文件不可能每次手动粘贴复制。这里建议把 mermaid-cli 装进开发依赖。它底层通过 Puppeteer 调用浏览器渲染，因此首次运行时需要下载浏览器内核，使用过程中要确保能正常访问 npm 源或者镜像。

安装方式可以参考：

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

或者作为项目依赖安装：

npm install --save-dev @mermaid-js/mermaid-cli

然后就可以把 Mermaid 文本文件导出为 SVG 或 PNG：

npx mmdc -i docs/diagrams/flow.mmd -o docs/images/flow.svg -c mermaid-theme.json

如果希望导出 PNG，可以再指定宽高。最后生成的 SVG 体积小、清晰度好，适合保留在 Git 仓库里。PNG 适合插入到不依赖 HTML 渲染的 RSS 或 PDF 文档中。

5.2 通过文档站点插件自动渲染

以 VitePress 为例，通常需要在 config 里开启 Mermaid 支持，并在构建时引入对应的主题插件。为了避免不同页面跳转后图表没有重新渲染，需要留意插件是否跟随路由切换执行了 mermaid.run()。实际项目中更稳妥的做法是，让渲染流程跟着站点构建跑一遍，每次代码合并后自动生成新的图。

这类站点插件一般会在所有 Markdown 内容转换完后统一解析带有 mermaid 语言标识的代码块，然后调用 Mermaid 的 JavaScript API 渲染成 SVG。因为流程图被嵌入了 HTML，最终页面里的文字可以选中，也能被浏览器无障碍工具读取。

5.3 在 CI 里检查渲染结果

如果不想在文档站点里每次重新构建时才发现某个 Mermaid 图语法有问题，可以写一个轻量的 CI 检查步骤：把仓库里所有 Mermaid 代码块抽出来，用 mermaid-cli 试渲染。渲染失败就中断流水线，并输出文件名和行号。引入这个检查之后，“文档图坏了”基本上不会等到发布才被发现。

下面是一个用 Node.js 批量扫描 Markdown 中的 mermaid 代码块，并逐个调用 mmdc 文件渲染的示例思路：

const fs = require('node:fs'); const path = require('node:path'); const { execFileSync } = require('node:child_process'); function extractMermaidBlocks(mdPath) { const content = fs.readFileSync(mdPath, 'utf8'); const pattern = /```mermaid\n([\s\S]*?)\n```/g; const blocks = []; let match; while ((match = pattern.exec(content)) !== null) { blocks.push({ content: match[1], line: content.slice(0, match.index).split('\n').length + 1 }); } return blocks; } function writeTempFile(block, index) { const tempDir = path.join(process.cwd(), '.tmp-diagrams'); fs.mkdirSync(tempDir, { recursive: true }); const filePath = path.join(tempDir, `block-${index}.mmd`); fs.writeFileSync(filePath, block.content, 'utf8'); return filePath; } function checkFile(mdPath) { const blocks = extractMermaidBlocks(mdPath); blocks.forEach((block, index) => { const input = writeTempFile(block, index); try { execFileSync('npx', [ '-y', '@mermaid-js/mermaid-cli', '-i', input, '-o', `${input}.svg` ], { stdio: 'pipe' }); console.log(`ok: ${mdPath} block line ${block.line}`); } catch (error) { console.error(`failed: ${mdPath} block line ${block.line}`); if (error.stdout) console.error(error.stdout.toString()); throw error; } }); } const targetFiles = process.argv.slice(2); targetFiles.forEach(checkFile);

代码里逐文件读取内容、用正则抽取 Mermaid 块、临时写成 mmd 文件，再调用 mmdc。实际项目中可以把它封装为一个 lint 工具，在 Git pre-commit 或 CI 里执行。这样做的好处是，生成文档后每个图都已经经过一次真实渲染验证，而不是只看文本缩进对不对。

6. 批量任务与风格检查的工程化

6.1 为什么在自主 OSS 项目里要特别重视批量渲染

自主 OSS 项目的内容产出量大，尤其当 AI Agent 被授权修改文档时，一个提交可能会涉及 README、doc 目录、架构说明等多个文件。每个文件里可能都有 Mermaid 图。如果手工维护，要么完全依赖默认主题，要么在多个文件里重复粘贴样式配置。这两种方案都不适合长期项目。

批量渲染的统一思路是在仓库根目录放一份 mermaid-theme.json，并且所有显式需要特殊定制的地方都通过 init 指令做局部覆盖。每次提交后运行一次批量导出，把文档中用到的图按约定目录导出为 SVG。导出文件可以纳入版本控制，也可以由 CI 发布到静态站点目录。

6.2 批量导出目录组织建议

docs/ diagrams/ source/ architecture.mmd >