读懂 Mermaid 的 CHANGELOG：Changesets 驱动的发布流程与 11.x 版本演进全解

packages/mermaid/CHANGELOG.md 是 Mermaid 官方维护的版本日志，覆盖从 0.2.x 到 11.17.0 的全部发布记录。本文以这份日志为主体，讲解 Mermaid 版本日志的生成机制（Changesets 工作流）、条目结构与阅读方法，并逐版本梳理 11.x 系列中的关键功能、破坏性变更与安全补丁，帮助你在选型、升级和排错时把 CHANGELOG 当作可靠的工程参照。

一、CHANGELOG 的位置与生成机制

1.1 文件位置：包内主文件 + 根目录软链接

Mermaid 的根目录 CHANGELOG.md 实际是一个指向包内文件的软链接（CHANGELOG.md -> ./packages/mermaid/CHANGELOG.md），真正的版本日志维护在 packages/mermaid/CHANGELOG.md 中。这意味着日志跟随 mermaid 这个 npm 包（而非 monorepo 内其他包）的版本节奏更新，日志中 # mermaid 一级标题下的每一条 ## <版本号> 对应一次 mermaid 包的发布。

1.2 Changesets 工作流

从仓库配置可以确认 Mermaid 使用 [Changesets](https://changesets.com 的概念由配置佐证)（@changesets/cli）生成版本日志：

• .changeset/config.json 中声明了 changelog 插件为 @changesets/changelog-github（repo: mermaid-js/mermaid）、baseBranch: master，并将 @mermaid-js/docs、@mermaid-js/webpack-test、@mermaid-js/mermaid-example-diagram 列入 ignore——即这三个包不参与版本与日志生成；
• 根 package.json 中定义了发布脚本：
  • changeset:version：执行 changeset version && pnpm build，随后调用 pnpm --filter mermaid run docs:release-version（对应 scripts 中的 tsx scripts/update-release-version.mts，用于同步文档中的版本号）与 docs:build，最后 git add --all 提交；
  • changeset:publish：执行 pnpm copy-readme && changeset publish 完成 npm 发布。

.changeset/ 目录下平时会保留尚未发布的变更说明文件（如 add-usecase-diagrams.md、c4-boundary-relation-endpoint.md、line-break-closing-tag.md），这些就是社区 PR 中随代码提交、等待下一次版本合并的"变更草稿"。理解了这条流水线，就能解释日志条目的统一格式：每条都带有 PR 编号、commit 短哈希和贡献者署名，这正是 @changesets/changelog-github 插件从 GitHub 元数据中回填的结果。

1.3 一致性自检

packages/mermaid/package.json 中的 version 字段当前为 11.17.0，与 CHANGELOG 中最新的 ## 11.17.0 小节完全一致。此外 mermaid 包的 prepublishOnly 脚本会执行 docs:verify-version（tsx scripts/update-release-version.mts --verify），从构建流程上约束了"发版必须同步版本号与文档"。因此可以推断：日志中的版本号与 npm 发布版本、文档站点声明的版本是强一致关系，读者可以放心以 CHANGELOG 顶部版本作为当前发布状态。

二、如何阅读一条 CHANGELOG 条目

日志中每个版本小节遵循固定结构：

## 11.17.0

### Minor Changes
- [#PR号] [`commit短哈希`] Thanks [@贡献者]! - 变更描述（可能附多行说明）

### Patch Changes
- ...
- Updated dependencies [commit短哈希]:
  - @mermaid-js/parser@1.2.1

• Minor / Patch 分级：遵循语义化版本，feat: 类条目落在 Minor，fix:/perf:/chore: 类条目落在 Patch；
• Updated dependencies 段：当 monorepo 内的依赖包（主要是 Langium 解析器包 @mermaid-js/parser）同步升级时出现，例如 11.17.0 携带 @mermaid-js/parser@1.2.1、11.13.0 携带 @mermaid-js/parser@1.0.1；
• 多行补充说明：涉及行为变更、配置回退方式的条目会附缩进段落，给出回滚配置或语法示例（下文第三节多处引用）；
• 历史格式：10.0.0 之前（## [10.0.0] 往下至 0.2.x）是早期手工维护格式，带链接的 ## [版本号] 标题和日期，信息粒度较粗。

三、v10.0.0 的 API 破坏性变更（升级必读）

日志中 10.0.0 一节明确列出四项破坏性变更，这是所有从 v9 迁移用户的"必背清单"：

3.1 仅支持 ESM

v10 移除了 CJS 支持，浏览器侧必须改用 type="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 版本继续消费旧的 UMD 构建。

3.2 mermaid.render 变为 async 且不再接受回调

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

旧的回调式 mermaid.render('id', text, (svg, bindFunctions) => {...}) 不再使用，日志同时给出 .then() 写法供不使用 await 的场景。

3.3 mermaid.parse 变为 async，ParseError 回调移除

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

3.4 init 弃用，InitThrowsErrors 移除

mermaid.init / mermaid.initThrowsErrors 被 initialize + run 组合替代：

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

日志还特别提示两点：v10 之后传入 init 的 config 会真正生效（此前被忽略），以及 globalReset 的行为变更为重置到 defaultConfig 而非当前配置，需要重置当前配置时应使用 reset。

四、11.x 新功能演进：从日志看路线图

4.1 新图表类型的加入与转正

按版本时间线，11.x 期间日志记录了如下新类型（括号内为当时可用的 diagram 头关键字）：

版本	新图表	日志要点
11.14.0	Wardley Maps（wardley-beta）	支持 OWM 坐标定位、锚点、多种连线、演化箭头、自定义演化阶段（@boundary）、策略标记（build/buy/outsource/market）、主题集成
11.14.0	TreeView	新增 TreeView diagram，后续 11.16.0 增加盒式绘图字符（box-drawing）输入支持与文件/目录结构特性
11.13.0	Venn（venn-beta）、Ishikawa（ishikawa-beta）	韦恩图与鱼骨图以 beta 引入
11.15.0	Event Modeling	事件建模图（eventmodeling）整体加入
11.16.0	Cynefin（cynefin-beta）	Dave Snowden 的五域复杂性决策框架，beta 引入
11.16.0	独立 Swimlane	swimlane 成为独立 diagram 类型，配专用分层正交布局算法
11.16.0	Railroad 语法图	支持四种输入语法：IR（railroad-beta）、EBNF、ABNF、PEG 变体

与之相对的"转正"事件同样有明确记录：11.10.0 移除 XYChart、Block、Sankey 三个类型的 -beta 后缀，11.9.0 将 packet 图移出 beta。仓库中与之对应的验证资产也成体系：demos/ 下存在 wardley.html、venn.html、usecase.html、treeView.html、railroad.html、sankey.html 等演示页，e2e/diagrams/ 下则有 wardley/、cynefin/、swimlanes/、tree-view/ 等截图回归目录，docs/syntax/ 中有 wardley.md、cynefin.md、venn.md、railroad.md、swimlanes.md 等语法文档——"日志条目 → 源码实现 → E2E 回归"三者在仓库内可以互相印证。

4.2 渲染器统一与 Neo 风格（11.14–11.17）

日志显示 11.x 后半段的主线是"统一渲染管线"：

• 11.14.0：为 flowchart、sequence、class、state、ER、requirement、mindmap、gitGraph、timeline 等类型逐一实现 "neo look" 样式（带投影的增强视觉风格）；同版本还引入了 architecture.randomize 配置（默认 false，保证架构图文本确定性布局）；
• 11.17.0：classDiagram 默认路由到统一（v2）渲染器，日志明确给出回退方式——在配置中设置 class: { defaultRenderer: 'dagre-d3' } 可恢复旧渲染器；C4 元素也改为经由统一形状系统（unified shape system）渲染并使用新的 person 形状。

4.3 形状（shape）系统的持续扩充

@{ shape: ... } 属性语法是 11.x 的标志性能力，日志中按版本记录了新增形状：

• 11.15.0：datastore（数据流图中的数据存储，A@{ shape: datastore, label: "Datastore" }）；
• 11.17.0：person（圆形头部 + 圆角身体）、folder、bucket、console（终端窗口）、browser。

这些形状与 @mermaid-js/parser 的语法包配合演进（例如 11.13.0 记录的 @mermaid-js/parser@1.0.1 依赖升级）。

4.4 布局引擎（ELK / dagre / fcose）的可调性

日志中多条与布局引擎相关的条目值得注意：

• 11.13.0 的边曲线变更：默认 flowchart 边曲线从 basis（平滑样条）改为 rounded（直角折线 + 圆角），用于修复 ELK 布局中"应走直角却弯曲"的问题；日志同时给出回退配置 flowchart.curve: 'basis'；
• 11.10.0：把 ELK 的 forceNodeModelOrder、considerModelOrder 暴露到 mermaid 配置；
• 11.17.0：新增 elk.keepEntryNodeOnTop（保持递归流程的入口节点在顶部）与 elk.nodePlacementAlignment 两个 ELK 配置项；
• 11.15.0：为 architecture-beta 暴露四个 fcose 布局旋钮：nodeSeparation、idealEdgeLengthMultiplier、edgeElasticity、numIter，并可在 11.16.0 用 align row|column {ids…} 指令显式声明对齐；
• 11.17.0 的性能条目：使用 fastdom 批量 DOM 测量，日志声称最高约 25% 的提速（此为日志原文的性能描述，未在仓库中另行给出基准数据）；同版本还修复了 dagre 布局日志刷屏问题，并让图自身的 nodeSpacing/rankSpacing 在统一 dagre 布局中生效。

五、升级时需要关注的行为变更清单

CHANGELOG 中带有"回退方法"或"行为反转"语义的条目是升级评审的重点，以下按版本汇总（均出自日志原文）：

版本	变更	日志给出的回退/注意事项
11.17.0	classDiagram 默认改用统一（v2）渲染器	配置 class.defaultRenderer: 'dagre-d3' 恢复旧渲染器
11.17.0	回退了 #7672（子图 direction 在 dagre 中的处理），原因是子图间箭头被打断	属于对上一轮修复的行为回滚，日志明确说明动机
11.16.1	弃用 mermaidAPI.setConfig()	日志指出该函数调用已无可观察效果（下次 render()/parse() 会清空 currentConfig）
11.15.0	class 图引入点号/语法嵌套命名空间	想要 ≤11.14.0 的扁平行为，配置 class.hierarchicalNamespaces: false（日志附 YAML 示例）
11.14.0	同页渲染多图时，内部元素 ID 统一加图级 SVG ID 前缀	自定义 CSS/JS 若用 #arrowhead 这类精确 ID 选择器，需改用 [id$="-arrowhead"] 之类的后缀选择器
11.14.0	流程图 TD 方向行为对齐 TB	日志标注为行为统一
11.13.0	弃用 flowchart.htmlLabels，推荐根级 htmlLabels	统一标签渲染策略
11.13.0	纯文本 flowchart 标签不再被误判为 markdown，<、& 不再在 htmlLabels: false 时被转义	想要 markdown 效果需用 node["md"] 反引号包裹写法（日志附完整示例）
11.15.0	stateDiagram 中以单个 % 开头的文本不再被视为注释	需要注释时改用 %%

对"配置项在哪生效"这类问题，日志本身就给出了最权威的答案格式：每条破坏性变更都内联了配置键名与示例，可与 docs/config/ 中的配置文档交叉核对。

六、安全补丁在日志中的呈现方式

11.x 日志中安全相关条目均带有明确的漏洞编号，可作为安全升级的依据：

• 11.16.1：增强原型污染防护，修复编号 GHSA-c4c3-pg64-4m4v；同时改进 compileCSS 对 CSS 兄弟组合子的处理，并把 architecture 图的 group/service 存储改为 Map/Set（服务按定义顺序渲染、支持更多 service ID）；
• 11.10.0：图标标签与图标 SVG 的清理（sanitize）对应 CVE-2025-54880，KaTeX 块清理对应 CVE-2025-54881；
• 11.15.0：放宽 uuid 依赖范围至允许 v14，以消除针对 CVE-2026-41907 的 npm audit 告警（日志说明 mermaid 未使用该库的受影响代码）；
• 11.12.1：升级 dagre-d3-es 至 7.0.13，修复 GHSA-cc8p-78qf-8p7q。

这类条目的阅读价值在于：当你只需要修漏洞而不想追平全部新功能时，日志能精确定位"从哪个版本开始安全"。

七、把 CHANGELOG 用于版本选型与排错

综合上述分析，这份日志对使用者的三类实际用途：

1. 升级评估：按 ## <版本> 自上而下扫描，重点核对带回退配置说明的 Minor 条目与第五节汇总表中的行为变更，确认自己的图与 CSS 不受影响；
2. 能力定位：想知道"某个新语法从哪个版本可用"，直接检索日志（如 person 形状、ER subgraph 支持均为 11.17.0；cynefin-beta 为 11.16.0），并与 docs/syntax/ 的语法文档、e2e/diagrams/ 的回归样例对照；
3. 问题回溯：当某功能出现回归时，日志中的 revert 记录（如 11.17.0 回退 #7672、11.10.0 将 marked 从 ^15 回退到 ^16）提供了明确的行为边界。

需要说明的适用前提：本文所依据的日志截至仓库当前的 11.17.0；10.0.0 之前的早期版本条目为旧格式、信息粒度较粗，引用具体细节时建议以对应时期的文档为准。版本日志由 Changesets 在 changeset:version/changeset:publish 流程中自动生成并提交（见 package.json 脚本与 .changeset/config.json），因此其内容与 npm 发布版本保持机制上的一致。