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-githubrepo 为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向后兼容的新功能featPatch Changes修复fix、依赖升级chore与安全加固。由于 Mermaid 是 pnpm 工作区见 pnpm-workspace.yaml包含packages/*与tests/*主包版本变动会带动工作区内部依赖同步因此条目末尾常见- Updated dependencies: - mermaid-js/parser1.2.1这提示读者解析器已从独立的mermaid-js/parser包演进而来gitGraph 在 11.0.2 迁移到 Langium见 11.0.2 条目升级 mermaid 主包时 parser 版本会联动变化。二、11.17.0classDiagram 渲染器切换与 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: falsepackages/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、personflowchart 新增了数据流图常用的存储类形状采用统一形状元数据语法其中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.111.16.1 是安全相关的重要版本changelog 记录了四件事原型污染防护增强fix: increase protections against prototype pollution修复 GHSA-c4c3-pg64-4m4v说明用户可控输入此前已有防护此提交进一步收紧architecture 图内部数据结构改造改用Map/Set存储 groups/services副作用是服务现在按定义顺序渲染且支持更多服务 ID——这是一条隐性行为变更依赖原渲染顺序的旧图可能观感不同弃用mermaidAPI.setConfig()changelog 明确指出调用该函数没有任何可观察效果因为下次render()或parse()时currentConfig会被清空。如果你的集成代码还在用setConfig应迁移到mermaid.initialize()或parse/render的config选项修复compileCSS对 CSS 兄弟选择器的处理、xychart 零宽度 x 轴范围、radar ticks 上限 32 等。3.2 11.16.0 的新图类型批量上线11.16.0 是新图类型密集的版本从 changelog 可整理出以下带-beta后缀的新能力图类型说明关键配套cynefin-betaCynefin 决策框架图五个复杂度域含 seed 确定性、accessibility 指令支持见 e2e 用例e2e/diagrams/cynefin/railroad-beta/railroad-ebnf-beta/railroad-abnf-beta/railroad-peg-beta铁路图语法图支持 IR、EBNF、ABNF、PEG 四种输入对应文档 docs/syntax/railroad.mdswimlane独立图类型专用的分层正交布局算法对应文档 docs/syntax/swimlanes.mdgantt 多excludes/includes行长排除列表可拆分为带注释的分组—architecturealign row\|column {ids…}指令显式声明服务横向/纵向对齐—pie 环形图、图例位置与高亮扇区——ER 属性类型可选?后缀——treeView 框线字符输入、文件/目录结构增强——四、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.0Wardley 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 diagrams 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.0flowchart 默认曲线从 basis 改为 rounded11.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: basisin your config.该修复主要针对 ELK 布局下边缘本该直角走线却变成弧线的问题#7213并作用于所有共享渲染管线的图类型。升级后发现曲线风格变化属于预期行为而非 bug。五、安全修复追踪CVE/GHSA 条目怎么读CHANGELOG 中散落的若干条目构成了一条可追溯的安全时间线升级时值得对照11.12.1dagre-d3-es升级到 7.0.13修复 GHSA-cc8p-78qf-8p7q依赖漏洞11.10.0sanitize icon labels and icon SVGs与sanitize KATEX blocks分别对应 CVE-2025-54880、CVE-2025-5488111.4.x 11.3.0Bump dompurify to ^3.2.1移除types/dompurify依赖与Ban DOMPurify v3.1.7 as a dependency——后者说明 3.1.7 因自身漏洞被主动排除在依赖范围外11.15.0loosen uuid dependency range to allow v14changelog 解释 mermaid 未使用 CVE-2026-41907 涉及的可疑代码但放宽版本范围可让用户消除npm audit告警11.16.1原型污染防护增强GHSA-c4c3-pg64-4m4v。另外 pnpm-workspace.yaml 中的minimumReleaseAge: 43203 天与minimumReleaseAgeExclude白名单表明项目对 Renovate 自动升级设置了最小发布年龄策略安全更新dompurify、ajv、vite 等被显式豁免可从仓库配置层面理解其依赖更新节奏。六、v10 迁移指南CHANGELOG 中保留的破坏性变更全文CHANGELOG 第 10.0.0 一节约 852 行起是 v9 → v10 的权威迁移参考共四类破坏性变更其代码示例应完整保留。6.1 Mermaid 变为 ESM onlyCJS 支持被移除浏览器端引入方式改为 module 脚本script typemodule import mermaid from https://cdn.jsdelivr.net/npm/mermaid10/dist/mermaid.esm.min.mjs; mermaid.initialize({ startOnLoad: true }); /script需要留在 v9 的可在 CDN URL 上加9- script srchttps://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.js/script script srchttps://cdn.jsdelivr.net/npm/mermaid9/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 变为 asyncParseError 被移除// 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 原文为准现象引入版本changelog 依据classDiagram 布局变化11.17.0默认切换统一渲染器class.defaultRenderer: dagre-d3可回退flowchart 边缘变直角圆角11.13.0默认curve由basis改roundedflowchart.curve: basis可回退页面内多图 CSS 选择器失效11.14.0内部元素 ID 加图级前缀改[id$-xxx]选择器纯文本标签自动换行、markdown 需显式包裹11.13.0#7276需 markdown 时用双引号反引号node[**bold**]architecture 服务渲染顺序变化11.16.1改用 Map/Set 存储按定义顺序渲染11.4.0 起类图新渲染管线11.4.0统一渲染、classBox 形状、classDef、handDrawn 支持XYChart/Block/Sankey 去 beta11.10.0图类型稳定化直接可用正式名称getRegisteredDiagramsMetadata()API11.9.0运行时枚举已注册图类型新增图类型各 minorpacket(11.7.0 前 beta→11.9.0 转正)、kanban(11.4.0)、architecture(11.1.0)、wardley-beta(11.14.0)、cynefin-beta/railroad/swimlane(11.16.0)、event modeling(11.15.0)、nested treemap(11.8.0)、ishikawa-beta/venn-beta(11.13.0)八、如何在仓库中继续深入阅读完整发布记录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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mermaid CHANGELOG 深度解读：从 11.x 版本演进到 v10 破坏性变更的升级实战指南
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-githubrepo 为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向后兼容的新功能featPatch Changes修复fix、依赖升级chore与安全加固。由于 Mermaid 是 pnpm 工作区见 pnpm-workspace.yaml包含packages/*与tests/*主包版本变动会带动工作区内部依赖同步因此条目末尾常见- Updated dependencies: - mermaid-js/parser1.2.1这提示读者解析器已从独立的mermaid-js/parser包演进而来gitGraph 在 11.0.2 迁移到 Langium见 11.0.2 条目升级 mermaid 主包时 parser 版本会联动变化。二、11.17.0classDiagram 渲染器切换与 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: falsepackages/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、personflowchart 新增了数据流图常用的存储类形状采用统一形状元数据语法其中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.111.16.1 是安全相关的重要版本changelog 记录了四件事原型污染防护增强fix: increase protections against prototype pollution修复 GHSA-c4c3-pg64-4m4v说明用户可控输入此前已有防护此提交进一步收紧architecture 图内部数据结构改造改用Map/Set存储 groups/services副作用是服务现在按定义顺序渲染且支持更多服务 ID——这是一条隐性行为变更依赖原渲染顺序的旧图可能观感不同弃用mermaidAPI.setConfig()changelog 明确指出调用该函数没有任何可观察效果因为下次render()或parse()时currentConfig会被清空。如果你的集成代码还在用setConfig应迁移到mermaid.initialize()或parse/render的config选项修复compileCSS对 CSS 兄弟选择器的处理、xychart 零宽度 x 轴范围、radar ticks 上限 32 等。3.2 11.16.0 的新图类型批量上线11.16.0 是新图类型密集的版本从 changelog 可整理出以下带-beta后缀的新能力图类型说明关键配套cynefin-betaCynefin 决策框架图五个复杂度域含 seed 确定性、accessibility 指令支持见 e2e 用例e2e/diagrams/cynefin/railroad-beta/railroad-ebnf-beta/railroad-abnf-beta/railroad-peg-beta铁路图语法图支持 IR、EBNF、ABNF、PEG 四种输入对应文档 docs/syntax/railroad.mdswimlane独立图类型专用的分层正交布局算法对应文档 docs/syntax/swimlanes.mdgantt 多excludes/includes行长排除列表可拆分为带注释的分组—architecturealign row\|column {ids…}指令显式声明服务横向/纵向对齐—pie 环形图、图例位置与高亮扇区——ER 属性类型可选?后缀——treeView 框线字符输入、文件/目录结构增强——四、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.0Wardley 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 diagrams 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.0flowchart 默认曲线从 basis 改为 rounded11.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: basisin your config.该修复主要针对 ELK 布局下边缘本该直角走线却变成弧线的问题#7213并作用于所有共享渲染管线的图类型。升级后发现曲线风格变化属于预期行为而非 bug。五、安全修复追踪CVE/GHSA 条目怎么读CHANGELOG 中散落的若干条目构成了一条可追溯的安全时间线升级时值得对照11.12.1dagre-d3-es升级到 7.0.13修复 GHSA-cc8p-78qf-8p7q依赖漏洞11.10.0sanitize icon labels and icon SVGs与sanitize KATEX blocks分别对应 CVE-2025-54880、CVE-2025-5488111.4.x 11.3.0Bump dompurify to ^3.2.1移除types/dompurify依赖与Ban DOMPurify v3.1.7 as a dependency——后者说明 3.1.7 因自身漏洞被主动排除在依赖范围外11.15.0loosen uuid dependency range to allow v14changelog 解释 mermaid 未使用 CVE-2026-41907 涉及的可疑代码但放宽版本范围可让用户消除npm audit告警11.16.1原型污染防护增强GHSA-c4c3-pg64-4m4v。另外 pnpm-workspace.yaml 中的minimumReleaseAge: 43203 天与minimumReleaseAgeExclude白名单表明项目对 Renovate 自动升级设置了最小发布年龄策略安全更新dompurify、ajv、vite 等被显式豁免可从仓库配置层面理解其依赖更新节奏。六、v10 迁移指南CHANGELOG 中保留的破坏性变更全文CHANGELOG 第 10.0.0 一节约 852 行起是 v9 → v10 的权威迁移参考共四类破坏性变更其代码示例应完整保留。6.1 Mermaid 变为 ESM onlyCJS 支持被移除浏览器端引入方式改为 module 脚本script typemodule import mermaid from https://cdn.jsdelivr.net/npm/mermaid10/dist/mermaid.esm.min.mjs; mermaid.initialize({ startOnLoad: true }); /script需要留在 v9 的可在 CDN URL 上加9- script srchttps://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.js/script script srchttps://cdn.jsdelivr.net/npm/mermaid9/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 变为 asyncParseError 被移除// 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 原文为准现象引入版本changelog 依据classDiagram 布局变化11.17.0默认切换统一渲染器class.defaultRenderer: dagre-d3可回退flowchart 边缘变直角圆角11.13.0默认curve由basis改roundedflowchart.curve: basis可回退页面内多图 CSS 选择器失效11.14.0内部元素 ID 加图级前缀改[id$-xxx]选择器纯文本标签自动换行、markdown 需显式包裹11.13.0#7276需 markdown 时用双引号反引号node[**bold**]architecture 服务渲染顺序变化11.16.1改用 Map/Set 存储按定义顺序渲染11.4.0 起类图新渲染管线11.4.0统一渲染、classBox 形状、classDef、handDrawn 支持XYChart/Block/Sankey 去 beta11.10.0图类型稳定化直接可用正式名称getRegisteredDiagramsMetadata()API11.9.0运行时枚举已注册图类型新增图类型各 minorpacket(11.7.0 前 beta→11.9.0 转正)、kanban(11.4.0)、architecture(11.1.0)、wardley-beta(11.14.0)、cynefin-beta/railroad/swimlane(11.16.0)、event modeling(11.15.0)、nested treemap(11.8.0)、ishikawa-beta/venn-beta(11.13.0)八、如何在仓库中继续深入阅读完整发布记录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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考