企业官网建设流程全解析

Mermaid CHANGELOG 深度解读：从 11.x 版本演进到 v10 破坏性变更的升级实战指南

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

本文以 Mermaid 仓库根目录的 CHANGELOG.md 为主体，解读其版本记录的生成机制（Changesets）与结构约定，逐一梳理 11.17.0 至 11.0 的关键功能、配置项变更与安全修复，并结合仓库源码验证这些变更的实际落点。读完后，你将能够看懂 Mermaid 每条 changelog 条目的含义，掌握 v10 异步 API 的迁移写法，并在升级依赖时准确评估破坏性变更的影响范围。

一、CHANGELOG.md 是什么、如何生成

仓库根目录的 CHANGELOG.md 实际上是一个指向 packages/mermaid/CHANGELOG.md 的符号链接，当前共 1852 行，覆盖从 11.17.0（对应 packages/mermaid/package.json 中version: "11.17.0"）一路回溯到 2016 年早期版本的完整发布历史。

1.1 由 Changesets 自动生成的 GitHub 风格日志

从源码结构看，Mermaid 使用 Changesets 工具链管理版本日志，而非手写：

• 根 package.json 中定义了发布脚本："changeset:version": "changeset version && pnpm build && ..."与"changeset:publish": "pnpm copy-readme && changeset publish"，并依赖@changesets/cli和@changesets/changelog-github；
• .changeset/config.json 指定日志模板为@changesets/changelog-github（repo 为mermaid-js/mermaid），这正是 CHANGELOG 中每条记录都带 PR 链接、commit 短哈希与贡献者致谢的原因；
• .changeset/目录下还存在若干未发布的变更说明文件（如add-usecase-diagrams.md、c4-boundary-relation-endpoint.md、line-break-closing-tag.md），从源码结构看，这就是待并入下一个版本的 changeset 草稿。

1.2 条目结构约定

阅读 CHANGELOG 时，每条记录遵循固定格式：

- #PR号 `commit短哈希` Thanks [@贡献者]! - 变更说明

每个版本按语义化版本（SemVer）拆分为两小节：

• Minor Changes：向后兼容的新功能（feat）；
• Patch Changes：修复（fix）、依赖升级（chore）与安全加固。

由于 Mermaid 是 pnpm 工作区（见 pnpm-workspace.yaml，包含packages/*与tests/*），主包版本变动会带动工作区内部依赖同步，因此条目末尾常见：

- Updated dependencies: - @mermaid-js/parser@1.2.1

这提示读者：解析器已从独立的@mermaid-js/parser包演进而来（gitGraph 在 11.0.2 迁移到 Langium，见 11.0.2 条目），升级 mermaid 主包时 parser 版本会联动变化。

二、11.17.0：classDiagram 渲染器切换与 ELK 布局新配置

11.17.0 是本日志中最新的版本，其中两条变更直接涉及运行时行为与配置，值得重点掌握。

2.1 classDiagram 默认切换到统一渲染器

changelog 原文：

feat(class): routeclassDiagramto the unified (v2) renderer by default Setclass: { defaultRenderer: 'dagre-d3' }in the config to restore the legacy renderer.

源码可以印证这一点：packages/mermaid/src/defaultConfig.ts 中class.defaultRenderer的默认值为'dagre-wrapper'（统一渲染路径），而 packages/mermaid/src/config.type.ts 声明其取值范围为'dagre-d3' | 'dagre-wrapper' | 'elk'。渲染器路由逻辑位于 packages/mermaid/src/diagrams/class/classDetector-V2.ts 与 packages/mermaid/src/diagrams/class/classDetector.ts，两者都会检查config?.class?.defaultRenderer决定是否走 V2 管线。如果你升级后类图布局发生变化，恢复旧行为只需：

mermaid.initialize({ class: { defaultRenderer: 'dagre-d3' } });

2.2 两个新的 ELK 布局配置项

11.17.0 引入：

• elk.keepEntryNodeOnTop：让递归流程的入口节点保持在最上层；
• elk.nodePlacementAlignment：控制子图节点对齐方式。

在 packages/mermaid/src/defaultConfig.ts 中可确认默认值：nodePlacementAlignment: 'NONE'、keepEntryNodeOnTop: false；packages/mermaid/src/config.type.ts 将对齐取值限定为'NONE' | 'LEFTUP' | 'LEFTDOWN' | 'RIGHTUP' | 'RIGHTDOWN' | 'BALANCED'。行为验证可见 packages/mermaid-layout-elk/src/tests/render.spec.ts 中的测试用例：启用keepEntryNodeOnTop时会把环状入口节点固定到第一层（"pins the cyclic entry node to the first layer"），默认关闭则不约束任何节点。

2.3 新节点形状：folder、bucket、console、browser、person

flowchart 新增了数据流图常用的存储类形状，采用统一形状元数据语法：

其中person（圆形头部加圆角身体）同时也是 11.17.0 中 C4 图渲染的基础——changelog 同时记录 "render C4 elements through the unified shape system, using the new person shape"。此外还新增了可折叠子图语法subgraphId@{ view: collapsed }、ER 图子图支持，以及 xyChart 的命名 series 图例。

三、11.16.x：安全加固与 API 弃用

3.1 原型污染防护与 setConfig 弃用（11.16.1）

11.16.1 是安全相关的重要版本，changelog 记录了四件事：

1. 原型污染防护增强（fix: increase protections against prototype pollution，修复 GHSA-c4c3-pg64-4m4v），说明用户可控输入此前已有防护，此提交进一步收紧；
2. architecture 图内部数据结构改造：改用Map/Set存储 groups/services，副作用是"服务现在按定义顺序渲染，且支持更多服务 ID"——这是一条隐性行为变更，依赖原渲染顺序的旧图可能观感不同；
3. 弃用mermaidAPI.setConfig()：changelog 明确指出"调用该函数没有任何可观察效果，因为下次render()或parse()时currentConfig会被清空"。如果你的集成代码还在用setConfig，应迁移到mermaid.initialize()或parse/render的config选项；
4. 修复compileCSS对 CSS 兄弟选择器的处理、xychart 零宽度 x 轴范围、radar ticks 上限 32 等。

3.2 11.16.0 的新图类型批量上线

11.16.0 是"新图类型"密集的版本，从 changelog 可整理出以下带-beta后缀的新能力：

四、11.15.0 ～ 11.14.0：嵌套命名空间、Wardley 图与 neo 风格

4.1 嵌套命名空间与回退开关

11.5.0 起 classDiagram 支持点号记法与语法嵌套的命名空间，changelog 特意给出了向后兼容开关：

config: class: hierarchicalNamespaces: false

若你的类图命名空间名本身含.且希望保持 11.14.0 及以前"不嵌套"的渲染行为，需在 mermaid config 中设置该值。同版本还包含 sequenceautonumber支持十进制起始/步长、flowchartdatastore形状（A@{ shape: datastore, label: "Datastore" }）、Event Modeling 图、architecture 暴露四个 fcose 布局旋钮（nodeSeparation、idealEdgeLengthMultiplier、edgeElasticity、numIter）、class 嵌套命名空间等。

4.2 11.14.0：Wardley Maps 与 SVG 元素 ID 前缀化

11.14.0 引入了wardley-beta图类型（组件 [可见性, 演化] 坐标、锚点、多类型链接、演化箭头等，见 docs/syntax/wardley.md），以及 state/sequence/ER/requirement/mindmap/flowchart/gitGraph/timeline/class 等多数图类型的 neo look 风格。

其中一条对下游 CSS 有破坏性的修复必须注意：

Fix duplicate SVG element IDs when rendering multiple diagrams on the same page. Internal element IDs (nodes, edges, markers, clusters) are now prefixed with the diagram's SVG element ID across all diagram types.

即同一页面渲染多张图时，内部元素 ID 现在带图级前缀。changelog 明确给出迁移建议：自定义 CSS/JS 若使用精确 ID 选择器（如#arrowhead），应改用属性后缀选择器[id$="-arrowhead"]。仓库中 e2e/platform/marker_unique_id.html 与 e2e/rendering/marker_unique_id.spec.js 即为该行为的回归测试。

4.3 11.13.0：flowchart 默认曲线从 basis 改为 rounded

11.13.0 的一条重要默认值变更：

The default flowchart edge curve changes frombasis(smooth splines) torounded(right-angle segments with rounded corners). To restore the previous smooth curve behavior, setflowchart.curve: 'basis'in your config.

该修复主要针对 ELK 布局下"边缘本该直角走线却变成弧线"的问题（#7213），并作用于所有共享渲染管线的图类型。升级后发现曲线风格变化，属于预期行为而非 bug。

五、安全修复追踪：CVE/GHSA 条目怎么读

CHANGELOG 中散落的若干条目构成了一条可追溯的安全时间线，升级时值得对照：

• 11.12.1：dagre-d3-es升级到 7.0.13，修复 GHSA-cc8p-78qf-8p7q（依赖漏洞）；
• 11.10.0：sanitize icon labels and icon SVGs与sanitize KATEX blocks，分别对应 CVE-2025-54880、CVE-2025-54881；
• 11.4.x ～ 11.3.0：Bump dompurify to ^3.2.1（移除@types/dompurify依赖）与Ban DOMPurify v3.1.7 as a dependency——后者说明 3.1.7 因自身漏洞被主动排除在依赖范围外；
• 11.15.0：loosen uuid dependency range to allow v14，changelog 解释 mermaid 未使用 CVE-2026-41907 涉及的可疑代码，但放宽版本范围可让用户消除npm audit告警；
• 11.16.1：原型污染防护增强（GHSA-c4c3-pg64-4m4v）。

另外 pnpm-workspace.yaml 中的minimumReleaseAge: 4320（3 天）与minimumReleaseAgeExclude白名单，表明项目对 Renovate 自动升级设置了"最小发布年龄"策略，安全更新（dompurify、ajv、vite 等）被显式豁免，可从仓库配置层面理解其依赖更新节奏。

六、v10 迁移指南：CHANGELOG 中保留的破坏性变更全文

CHANGELOG 第 10.0.0 一节（约 852 行起）是 v9 → v10 的权威迁移参考，共四类破坏性变更，其代码示例应完整保留。

6.1 Mermaid 变为 ESM only

CJS 支持被移除，浏览器端引入方式改为 module 脚本：

<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>

需要留在 v9 的，可在 CDN URL 上加@9：

- <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.js"></script> + <script src="https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.js"></script>

当前仓库 packages/mermaid/package.json 中"type": "module"与module: ./dist/mermaid.core.mjs与此一致。

6.2 mermaid.render 变为 async，不再接受回调

// < v10 mermaid.render('id', 'graph TD;\nA-->B', (svg, bindFunctions) => { element.innerHTML = svg; if (bindFunctions) { bindFunctions(element); } }); // >= v10 with async/await const { svg, bindFunctions } = await mermaid.render('id', 'graph TD;\nA-->B'); element.innerHTML = svg; bindFunctions?.(element); // >= v10 with promise.then mermaid.render('id', 'graph TD;A-->B').then(({ svg, bindFunctions }) => { element.innerHTML = svg; bindFunctions?.(element); });

6.3 mermaid.parse 变为 async，ParseError 被移除

// < v10 mermaid.parse(text, parseError); // >= v10 await mermaid.parse(text).catch(parseError); // or try { await mermaid.parse(text); } catch (err) { parseError(err); }

6.4 init / initThrowsErrors 弃用，替换为 initialize + run

// < v10 mermaid.init(config, selector, cb); // >= v10 mermaid.initialize(config); mermaid.run({ querySelector: selector, postRenderCallback: cb, suppressErrors: true, }); // initThrowsErrors 对应 suppressErrors: false mermaid.initialize(config); mermaid.run({ querySelector: selector, postRenderCallback: cb, suppressErrors: false, });

该节末尾还补充了两条易被忽略的说明：Config 有大量变化；globalReset现在重置到defaultConfig而非当前配置，应改用reset。

七、按版本回退时的快速对照表

基于 CHANGELOG 全文整理，常见"升级后行为变化"与对应版本对照如下（完整条目以 packages/mermaid/CHANGELOG.md 原文为准）：

八、如何在仓库中继续深入

• 阅读完整发布记录：packages/mermaid/CHANGELOG.md（根目录 CHANGELOG.md 为符号链接）；
• 查看配置项默认值与类型定义：packages/mermaid/src/defaultConfig.ts、packages/mermaid/src/config.type.ts；
• 查看 ELK 布局选项测试：packages/mermaid-layout-elk/src/tests/render.spec.ts；
• 查看待发布的 changeset 草稿：.changeset/ 目录下的.md文件；
• 查看各图类型语法参考（与 changelog 中新图类型条目相互印证）：docs/syntax/ 下的 flowchart.md、entityRelationshipDiagram.md、wardley.md、railroad.md、swimlanes.md 等；
• 社区贡献（含 changeset 用法）可参考 docs/community/contributing.md。

适用前提说明：本文所有配置项、默认值与 API 行为均以当前仓库（mermaid 11.17.0）的实际内容为依据；changelog 中引用的 PR/commit 链接指向上游仓库，本文不再重复列出。若你使用的工作区版本落后于 11.17.0，请以对应版本的 CHANGELOG 段落为准。

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid