mermaid.html 参数详解

mermaid.html

<script>
(function() {
  if (window.mermaidInitialized) return;
  window.mermaidInitialized = true;  // 移到开头防止重复加载

  var script = document.createElement('script');
  script.src = 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js';
  
  script.onload = function() {
    // 1. 初始化配置
    mermaid.initialize({
      theme: 'base',
      themeVariables: {
        background: 'transparent',
        primaryColor: '#ffffff',
        primaryBorderColor: '#333333',
        primaryTextColor: '#333333',
        lineColor: '#333333',
        lineWidth: '2px',
        strokeWidth: '2px',
        secondaryColor: '#ffffff',
        tertiaryColor: '#ffffff',
        fontFamily: 'ui-sans-serif, system-ui, sans-serif',
        fontSize: '14px',
        borderRadius: '4px',
        edgeLabelBackground: '#ffffff'
      },
      flowchart: {
        curve: 'basis',
        padding: 20,
        nodeSpacing: 50,
        rankSpacing: 50
      }
    });

    // 2. 🔥 关键：调用 run() 时传入配置，确保样式生效
    mermaid.run({
      querySelector: '.mermaid',
      // 这里可以再次传入配置，覆盖 initialize 中的设置
      // 但更关键的是这个调用本身会触发渲染
    }).catch(function(err) {
      console.warn('Mermaid 渲染警告:', err);
    });
  };

  document.head.appendChild(script);
})();
</script>

恭喜调试成功！这段代码是一个标准且健壮的 Mermaid 加载器，它解决了 GitHub Pages 环境下 Markdown 解析与 Mermaid 渲染之间的兼容问题。

下面我把这段代码的核心逻辑和参数含义拆解成三个层面，帮你彻底理解它：

1. 代码整体运行逻辑（三部曲）

• 防重复加载：通过 window.mermaidInitialized 标志位，确保即使用户多次刷新或页面有多个脚本片段，也只会加载一次 mermaid.min.js 库。
• 动态注入 CDN：用 document.createElement('script') 异步加载 Mermaid 核心库（v10 版本），不阻塞博客页面的其他内容渲染。
• 初始化与执行：库加载完成后，调用 mermaid.initialize() 设置全局样式，然后用 mermaid.run() 扫描网页上所有带有 class="mermaid" 的元素（包括你写的 <pre class="mermaid">）并渲染成 SVG 图表。

---

2. mermaid.initialize({...}) 核心参数详解

这个配置对象决定了图表长什么样（颜色、粗细、排版）。

参数分类	参数名	你设置的值	具体含义
主题基石	theme	'base'	必须设为 base。只有这个主题允许你通过下面的 themeVariables 逐个调整颜色和尺寸，其他主题（如 default）会锁定配色方案，导致你写的 lineWidth 等参数被覆盖。
节点外观 (themeVariables)	primaryColor	'#ffffff'	节点的填充色（白色）。实现“不要涂色”的核心。
	primaryBorderColor	'#333333'	节点外边框颜色（深灰）。
	primaryTextColor	'#333333'	节点内文字颜色（深灰）。
	secondaryColor tertiaryColor	'#ffffff'	次要节点（如菱形、圆角矩形）的填充色，一并设为白色保持风格统一。
	borderRadius	'4px'	节点圆角大小。4px 是小圆角，让方框看起来更柔和现代。
线条控制 (themeVariables)	lineColor	'#333333'	连线的颜色（深灰）。
	lineWidth	'2px'	连线（箭头线）的粗细。你这里设了 2px，会比默认稍粗，适合文章阅读。
	strokeWidth	'2px'	节点边框的粗细。与上面区分开，你这里两者都设为了 2px，整体风格厚重、清晰。
排版辅助	fontFamily	'ui-sans-serif...'	字体栈。优先使用系统 UI 字体，渲染更快更清晰。
	fontSize	'14px'	节点内文字大小。
	edgeLabelBackground	'#ffffff'	连线中间文字标签（如果有）的背景底色，设为白色防止与连线重叠看不清。
流程图布局 (flowchart)	curve	'basis'	连线弯曲方式。basis 会让折线变为平滑的贝塞尔曲线，比默认的直角拐弯更现代。
	padding	20	图表边缘与最外层节点的间距。
	nodeSpacing	50	同一层级内，左右相邻节点的间距。数值越大图越宽。
	rankSpacing	50	不同层级之间（上下行）的间距。数值越大图越高。

---

3. 关键执行命令：mermaid.run()

• querySelector: '.mermaid'：这是渲染的目标选择器。它的意思是：“去找网页里所有 class="mermaid" 的 HTML 标签”。
• 为什么必须有这行：之前的 initialize 只是配置，不会主动绘图。run() 才真正启动渲染引擎。你的 <pre class="mermaid"> 就是通过这个选择器被捕获并转换成图形的。
• .catch 错误捕获：如果渲染过程中语法报错（比如括号不匹配），浏览器控制台会输出警告，方便你排查问题，而不会导致整个页面崩溃。

---

4. 补充一点小细节：window.mermaidInitialized

你将 true 赋值放在了 script 加载之前（顶部），这是一个优秀的工程习惯。如果在异步加载 Mermaid CDN 的几毫秒内，页面其他脚本再次调用这段代码，if 判断会直接拦截，防止重复下载同一个几十 KB 的库文件，显著提升页面性能。

现在的配置非常适合黑白打印或极简风格的技术博客，如果以后想换成彩色手绘风，重点调整 primaryColor（填充）和 lineWidth（粗细）这几个参数即可。干得漂亮！ 🎉