mermaid setConfig() API 详解签名、内部实现与弃用迁移路径【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本篇围绕 mermaid 配置系统中的setConfig()函数展开它的确切签名与参数语义、基于消毒sanitize 深度合并的内部实现链路、被官方标记为弃用的根本原因以及在新版 mermaid 中应当如何选用setSiteConfig、updateSiteConfig、addDirective等替代 API 完成同样的配置需求。读完本文你将能够理解 mermaid 三层配置模型defaultConfig / siteConfig / currentConfig的工作机制并安全地迁移存量代码中对setConfig()的调用。API 概览setConfig()是 mermaid 配置模块对外暴露的函数之一其自动生成 API 文档页位于 docs/config/setup/config/functions/setConfig.md同模块的完整函数索引见 docs/config/setup/config/README.md。该函数的核心信息如下函数签名setConfig(conf: MermaidConfig): MermaidConfig定义位置packages/mermaid/src/config.ts参数conf类型为MermaidConfig文档中描述为 The potential currentConfig即待合并进当前配置的配置对象返回值MermaidConfig即与消毒后的 conf 合并之后的 currentConfigThe currentConfig merged with the sanitized conf行为说明Updates thecurrentConfigwith the providedconfafter sanitization —— 在对该对象做安全消毒后将其更新进currentConfig弃用声明DeprecatedAny changes to thecurrentConfigwould be overwritten by the next call toaddDirectiveorreset—— 对currentConfig所做的任何改动都会被下一次addDirective()或reset()调用所覆盖该函数通过 packages/mermaid/src/diagram-api/diagramAPI.ts 的export const setConfig _setConfig;转发导出属于 mermaid 对外配置 API 的一部分。setConfig 在 mermaid 配置体系中的位置理解setConfig必须先理解 mermaid 的配置分层。从 packages/mermaid/src/config.ts 的模块级变量声明可以看出mermaid 维护了多份配置对象// packages/mermaid/src/config.ts export const defaultConfig: MermaidConfig Object.freeze(config); // 冻结的默认配置 let siteConfig: MermaidConfig assignWithDepth({}, defaultConfig); // 站点配置受保护的持久配置 let configFromInitialize: MermaidConfig; // mermaid.initialize() 传入的配置 let directives: MermaidConfig[] []; // 图表内 %%{init: ...}%% 指令累积 let currentConfig: MermaidConfig assignWithDepth({}, defaultConfig); // 渲染时真正生效的配置各层含义如下配置层来源用途defaultConfig模块内置Object.freeze冻结一切配置的起点不可变siteConfigsetSiteConfig/updateSiteConfig宿主站点受保护protected的重复使用配置reset()后currentConfig会回到这里configFromInitializesaveConfigFromInitialize用户在mermaid.initialize()中传入的配置directivesaddDirective累积每张图内%%{init: ...}%%指令解析出的配置片段currentConfig上述各层按优先级深度合并的结果渲染时实际读取的配置setConfig()的特殊之处在于它不经过siteConfig而是直接把传入的conf当作临时指令作用于currentConfig。这正是它容易被后续操作覆盖的原因——它没有写入任何持久层。源码实现剖析一次 setConfig 调用的完整链路setConfig的实现只有三行核心逻辑// packages/mermaid/src/config.ts L106-L110 export const setConfig (conf: MermaidConfig): MermaidConfig { updateCurrentConfig(currentConfig, [conf]); return getConfig(); };第一步进入 updateCurrentConfig 做消毒与深度合并updateCurrentConfig(siteCfg, _directives)config.ts以siteCfg为基座依次把_directives数组中的每一项合并进来。setConfig传入的[conf]会被当作一个指令处理const updateCurrentConfig (siteCfg: MermaidConfig, _directives: MermaidConfig[]) { let cfg: MermaidConfig assignWithDepth({}, siteCfg); // 从基座深拷贝起步 let sumOfDirectives: MermaidConfig {}; for (const d of _directives) { sanitize(d); // 1. 逐条消毒 sumOfDirectives assignWithDepth(sumOfDirectives, d); // 2. 指令间深合并 } cfg assignWithDepth(cfg, sumOfDirectives); // 3. 覆盖到基座之上 // 4. 若指令携带 theme则重新计算 themeVariables见下 currentConfig cfg; checkConfig(currentConfig); // 5. 触发弃用配置项的告警 return currentConfig; };这里的关键工具是assignWithDepth——一个深度合并函数区别于Object.assign的浅合并。Object.assign在合并嵌套对象时会整棵替换子树而assignWithDepth会逐层递归合并保留未覆盖的兄弟键。这正是为什么只改一个深层键也能安全工作的原因assignWithDepth与Object.assign的行为差异对照摘自 mermaid 配置文档的插图 docs/config/img/assignWithDepth.png这一点在 packages/mermaid/src/config.spec.ts 中有直接的行为验证——should allow setting partial options 用例configApi.setConfig({ quadrantChart: { chartHeight: 600, }, }); const updatedConfig configApi.getConfig(); // 未更新的深层选项应保持原值 expect(defaultConfig.quadrantChart!.chartWidth).toEqual( updatedConfig.quadrantChart!.chartWidth );即只传quadrantChart.chartHeight同级的chartWidth等字段不会被抹掉。第二步主题变量的特殊处理updateCurrentConfig中还有一段针对theme的专门逻辑config.ts当指令中声明了theme且该主题存在于内置主题表中时会取configFromInitialize的themeVariables与指令中的themeVariables深合并后交给对应主题的getThemeVariables()重算结果写回cfg.themeVariables。换言之setConfig传入主题名后主题变量不是简单赋值而是经过主题函数推导生成保证配色体系自洽。第三步getConfig 返回的是深拷贝setConfig末尾调用getConfig()config.tsexport const getConfig (): MermaidConfig { return assignWithDepth({}, currentConfig); };返回的是currentConfig的一份深度副本而非引用因此调用方拿到的配置对象可以安全保存、传递而不影响内部状态。源码注释还特意提醒Avoid calling this function repeatedly —— 应把结果存入变量复用而不是在渲染循环里反复调用。sanitizesetConfig 的安全边界after sanitization 是setConfig语义的核心承诺。真正执行消毒的是sanitize()config.ts文档页见 docs/config/setup/config/functions/sanitize.md。它对传入对象做三件事均就地修改options保护 secure 键遍历[secure, ...(siteConfig.secure ?? [])]如果 options 中带有这些键例如把securityLevel加入secure列表后的键则记录 debug 日志并delete掉。源码注释特别警告不要试图在${}中打印options[key]的值因为恶意脚本可能利用 logger 的字符串化执行任意代码。防原型污染删除所有以__开头的键阻断__proto__之类的原型污染路径。防 XSS字符串值中若包含、或url(data:整个键被删除——因为 base64 data URL 里可以藏内联脚本的 SVG对象值则递归继续消毒。packages/mermaid/src/config.spec.ts 的 should respect secure keys when applying directives 用例验证了这套机制站点先把fontSize与securityLevel声明为 secure 后再通过指令尝试改写二者最终getConfig()取回的仍是站点配置的值而未被保护的fontFamily则正常生效。为什么被弃用被覆盖的语义setConfig的弃用声明指出对currentConfig的改动会被下一次addDirective或reset覆盖。从源码结构看根源在于updateCurrentConfig的计算方式reset()config.ts会清空directives数组并以siteConfig为基座重新执行updateCurrentConfig。setConfig写入的内容只存在于currentConfig这一派生结果中一旦重算即被丢弃。addDirective()config.ts同样以siteConfig 全部directives重新推导currentConfigsetConfig的临时改动不在推导输入里。config.spec.ts 的两个 reset 用例精确刻画了这一行为setSiteConfig({fontFamily: foo-font, ...})之后调用setConfig({fontFamily: baf})getConfig()得到baf但reset()之后又回到foo-font。另一个用例中setConfig({altFontFamily: bar-font})的改动在reset()后变为undefined。也就是说setConfig只能影响当下到下次重算之间的配置状态无法表达持久意图。迁移指南用哪个 API 替代 setConfig根据需求的不同持久性推荐迁移到以下 API均在 packages/mermaid/src/config.ts 中定义且均不处于弃用状态需求场景推荐 API源码位置语义设置站点级、需跨图保持的基线配置setSiteConfig(conf)config.ts#L64-L76以defaultConfig为底重建siteConfig并深合并 conf带 theme 时重算themeVariables随后刷新currentConfig在已有站点配置上增量修改updateSiteConfig(conf)config.ts#L82-L87把 conf 深合并进现有siteConfig保留其余站点配置表达某一张图生效的配置addDirective(directive)config.ts#L173-L186对应图内%%{init: ...}%%指令会先sanitizeDirective并把孤立的fontFamily提升进themeVariables回到站点基线reset(config?)config.ts#L194-L198清空 directives默认以siteConfig重建currentConfig以典型迁移为例原代码// 旧写法临时改动随时可能被覆盖 mermaid.setConfig({ securityLevel: strict, flowchart: { htmlLabels: true } });若这些是站点全局策略应迁移为// 新写法写入受保护的站点配置层 mermaid.setSiteConfig({ securityLevel: strict, flowchart: { htmlLabels: true }, });若是单图级别的差异则改用图内%%{init: ...}%%指令经由addDirective进入配置链它同样经过sanitize消毒并参与主题变量推导。需要注意的适用前提与限制所有 API 均受sanitize的 secure 键约束securityLevel等敏感键能否被下游配置覆盖取决于siteConfig.secure的声明flowchart.htmlLabels自身已弃用见 config.ts 中的ConfigWarning.FLOWCHART_HTML_LABELS_DEPRECATED与getEffectiveHtmlLabels()推荐改用根级的htmlLabels本文所述行为以当前仓库 packages/mermaid/src/config.ts 的实现及其单元测试 packages/mermaid/src/config.spec.ts 为准具体键名与默认值请参考 MermaidConfig 类型定义与 defaultConfig 的当前值。小结setConfig()是 mermaid 配置体系早期形态的产物它通过updateCurrentConfig完成消毒 → 深度合并 → 主题推导三步把临时配置注入currentConfig并返回深拷贝结果。但由于其写入不落在siteConfig持久层会被addDirective或reset覆盖官方已将其弃用。对需要站点级持久配置的调用方应迁移至setSiteConfig/updateSiteConfig对单图级配置应使用 init 指令addDirective。理解这套三层模型与 sanitize 安全边界后可以在不破坏既有安全约束的前提下精确控制每张图的渲染参数。【免费下载链接】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），仅供参考