Mermaid setSiteConfig()：站点级配置（siteConfig）机制源码解析

Mermaid setSiteConfig()站点级配置siteConfig机制源码解析【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于 Mermaid 官方 API 文档 setSiteConfig.md结合 packages/mermaid/src/config.ts 的源码实现完整讲解 Mermaid 的 defaultConfig → siteConfig → currentConfig 三级配置模型、setSiteConfig的深合并与主题解析逻辑、secure安全边界以及initialize/reset/updateSiteConfig等配套 API 的协作方式。读完你可以正确完成站点级全局配置、理解为什么图作者通过指令无法改写某些配置项并在自定义渲染行为时定位到具体源码。一、setSiteConfig() 在 Mermaid 配置体系中的位置官方文档对setSiteConfig的定义如下该页为 TypeDoc 自动生成的 API 参考源文件位于仓库内packages/mermaid/src/docs/config/setup/config/functions/setSiteConfig.md文档中标注 DO NOT EDITsetSiteConfig(conf): MermaidConfigSets thesiteConfigto the desired values. ThesiteConfigis a protected configuration for repeat use. Calls to reset will reset thecurrentConfigtositeConfig. Defined in: packages/mermaid/src/config.ts:64 参数 confMermaidConfigThe config to use assiteConfig. This will be merged with thedefaultConfig. 返回值MermaidConfigThe new siteConfig。要理解这个函数先要看清 Mermaid 的配置分层。Configuration 文档 说明 Mermaid 启动时从以下来源提取配置defaultConfig内置默认值siteConfig由站点集成方通过initialize调用设置的站点级覆盖作用于该站点/应用中的所有图表Frontmatterv10.5.0图作者可以在图文件顶部的 YAML 块中覆盖选定的配置参数除 secure 配置外Directives已被 Frontmatter 取代图作者通过图代码中的指令直接更新选定配置参数。最终用于渲染的配置称为render config即上述各层合并后的结果。8.6.0 变更文档 则给出了经典的三级模型表述配置层级说明Global ConfigurationMermaid 的默认配置Site Configuration由站点所有者site owner设置Current Configuration由实现者/图作者implementor设置源码中的对应模块状态见 config.ts#L19-L22let siteConfig: MermaidConfig assignWithDepth({}, defaultConfig); let configFromInitialize: MermaidConfig; let directives: MermaidConfig[] []; let currentConfig: MermaidConfig assignWithDepth({}, defaultConfig);即siteConfig与currentConfig都起始于defaultConfig的深拷贝defaultConfig本身被Object.freeze冻结见 config.ts#L8而siteConfig每次变更都会触发currentConfig的刷新——这正是setSiteConfig的核心职责。二、setSiteConfig() 的签名、参数与返回值项目内容签名setSiteConfig(conf: MermaidConfig): MermaidConfig参数conf要用作siteConfig的配置会与defaultConfig做深合并返回值新的siteConfig完整对象默认值 conf 解析后的主题变量定义位置packages/mermaid/src/config.ts#L64文档入口docs/config/setup/config/functions/setSiteConfig.md配置函数索引见 docs/config/setup/config/README.md结合文档语义与源码有三点必须强调是重建而非叠加每次调用都从defaultConfig出发重新构建siteConfig因此conf相对默认值是全量声明而不是在上一次siteConfig上打补丁。需要增量合并时应改用updateSiteConfig见第六节。返回值是完整配置对象可直接用于后续判断或断言而不是只返回增量部分。立即同步渲染配置函数末尾的updateCurrentConfig(siteConfig, directives)保证调用后当前渲染配置即刻生效无需等待下一张图渲染。三、setSiteConfig 源码逐步拆解完整实现见 config.ts#L64-L76export const setSiteConfig (conf: MermaidConfig): MermaidConfig { siteConfig assignWithDepth({}, defaultConfig); siteConfig assignWithDepth(siteConfig, conf); if (conf.theme theme[conf.theme]) { siteConfig.themeVariables theme[conf.theme].getThemeVariables(conf.themeVariables); } updateCurrentConfig(siteConfig, directives); return siteConfig; };逐行解析siteConfig assignWithDepth({}, defaultConfig)深拷贝全局默认值。因为defaultConfig是冻结对象必须拷贝后才能安全修改且保证多次调用互不污染。siteConfig assignWithDepth(siteConfig, conf)把用户传入的conf深合并进默认值——这就是官方文档所说 This will be merged with the defaultConfig。注意合并语义中类型不同互不覆盖详见第四节。主题解析若conf.theme是已注册的主题名则调用该主题的getThemeVariables(conf.themeVariables)生成完整的themeVariables并写回siteConfig。这就是只传主题名加少量变量覆盖其余颜色体系自动补齐的实现原理。updateCurrentConfig(siteConfig, directives)以新siteConfig叠加当前累积的 directives 刷新currentConfig最后返回siteConfig。currentConfig 的刷新管线updateCurrentConfig刷新逻辑在 config.ts#L24-L53const updateCurrentConfig (siteCfg: MermaidConfig, _directives: MermaidConfig[]) { // start with config being the siteConfig let cfg: MermaidConfig assignWithDepth({}, siteCfg); // Join directives let sumOfDirectives: MermaidConfig {}; for (const d of _directives) { sanitize(d); sumOfDirectives assignWithDepth(sumOfDirectives, d); } cfg assignWithDepth(cfg, sumOfDirectives); if (sumOfDirectives.theme sumOfDirectives.theme in theme) { // ...以 theme 为基准重算 themeVariables } currentConfig cfg; checkConfig(currentConfig); return currentConfig; };三个关键点每条 directive 合并前先经过sanitize(d)处理——这是安全边界的执行点见第五节当合并结果包含有效theme时以该主题为基准重算themeVariablesconfig.ts#L39-L48因此指令只需声明主题名 要覆盖的变量最后执行checkConfigconfig.ts#L217-L225对弃用选项发出警告例如设置了lazyLoadedDiagrams/loadExternalDiagramsAtStartup时会提示改用registerExternalDiagrams。四、setSiteConfig 背后的深合并工具assignWithDepthsetSiteConfig的合并行为完全由assignWithDepth决定其实现见 packages/mermaid/src/assignWithDepth.ts语义如下任意深度递归合并对src中每个键递归执行合并目标对象缺失该键时先自动初始化为{}再合并不会因键缺失报错类型不同互不覆盖dissimilar types will not clobber例如dst.foo是{bar: bar}而src.foo是字符串foo结果为{bar: bar}。普通Object.assign会直接用foo覆盖对象结构assignWithDepth则保留原对象避免误传标量把默认配置结构打碎数组语义src是数组而dst不是数组时逐个元素依次合并两者都是数组时做去重并集支持depth参数控制递归深度默认 2。在 8.6.0 变更文档 中assignWithDepth也被列为该版本的关键新特性并被明确描述为类似Object.assign但带深度的对象合并机制上述图片即展示了两种合并方式的差异示例。五、安全边界secure 数组与 sanitizesiteConfig是受保护的站点级配置它同时是下层配置的安全边界定义者。sanitizeconfig.ts#L131-L166在每条 directive 并入currentConfig之前被调用做三类防护secure 键保护遍历[secure, ...(siteConfig.secure ?? [])]若指令携带其中任一键记录日志并就地删除——这正是图作者无法通过%%{init}%%指令抬高站点securityLevel等原因原型污染防护删除所有以__开头的键XSS 防护删除包含、或url(data:的字符串值因为 base64 的 data URL 可以内嵌含内联脚本的 SVG。需要精确区分的是传入setSiteConfig的conf来自可信的站点所有者不会被sanitize被清洗的是渲染管线中的每条 directive。secure的默认值定义在配置 Schema 中packages/mermaid/src/schemas/config.schema.yaml#L259-L276secure: description: | This option controls which currentConfig keys are considered secure and can only be changed via call to mermaid.initialize. This prevents malicious graph directives from overriding a sites default security. default: - secure - securityLevel - startOnLoad - maxTextSize - suppressErrorRendering - maxEdges8.6.0 变更文档 用套娃比喻解释了规则全局 secure 数组不可变站点所有者只能通过initialize追加如initialize({ secure: [secure, securityLevel, parameter1] })实现者图作者则完全不能修改该数组。注意 8.6.0 文档中的默认列表[secure, securityLevel, startOnLoad, maxTextSize]是早期快照当前仓库 Schema 还包含suppressErrorRendering与maxEdges以当前 Schema 为准。测试 packages/mermaid/src/config.spec.ts#L19-L38 精确验证了这条边界setSiteConfig将fontSize追加进 secure 后再通过addDirective尝试修改fontSize和securityLevel断言getConfig()返回的仍是站点值而fontFamily这类非 secure 项则正常生效。六、公共入口mermaid.initialize()站点集成方通常不直接调用setSiteConfig而是经由initializepackages/mermaid/src/mermaidAPI.ts#L663-L690function initialize(userOptions: MermaidConfig {}) { const options: MermaidConfig assignWithDepth({}, userOptions); // 兼容旧版顶层 fontFamily 迁移到 themeVariables.fontFamily if (options?.fontFamily !options.themeVariables?.fontFamily) { options.themeVariables { ...options.themeVariables, fontFamily: options.fontFamily, }; } // 记录 initialize 的原始输入 configApi.saveConfigFromInitialize(options); if (options?.theme options.theme in theme) { options.themeVariables theme[options.theme].getThemeVariables(options.themeVariables); } else if (options) { options.themeVariables theme.default.getThemeVariables(options.themeVariables); } const config typeof options object ? configApi.setSiteConfig(options) : configApi.getSiteConfig(); setLogLevel(config.logLevel); addDiagrams(); }要点官方文档明确 initialize只应调用一次The initialize call is applied only once它通过saveConfigFromInitialize先保存用户输入供 getUserDefinedConfig 后续读取再调用setSiteConfig(options)建立siteConfig顶层fontFamily属于旧版配置位置会被自动迁移进themeVariables.fontFamily主题解析在initialize与setSiteConfig中各有一次逻辑一致最后设置日志级别并注册内置图表。一个典型的站点级用法import mermaid from mermaid; mermaid.initialize({ startOnLoad: false, theme: forest, themeVariables: { primaryColor: #00ff00 }, fontFamily: monospace, secure: [secure, securityLevel, startOnLoad, maxTextSize, maxEdges, suppressErrorRendering], flowchart: { curve: basis }, });与之对照图作者implementor只能覆盖非 secure 项Configuration 文档 给出的 frontmatter 示例--- title: Hello Title config: theme: base themeVariables: primaryColor: #00ff00 --- flowchart Hello -- Worldfrontmatter 中整份配置除 secure 项外均可覆盖的边界正是第五节sanitize机制在解析层的体现。七、配套 API 全家福reset / getSiteConfig / updateSiteConfig / setConfigconfig.ts 围绕siteConfig暴露的一组 API官方索引见 docs/config/setup/config/README.mdAPI行为源码位置setSiteConfig(conf)以 默认值 conf 重建 siteConfig并刷新 currentConfigL64-L76updateSiteConfig(conf)在当前 siteConfig 上增量合并 conf 后刷新 currentConfigL82-L87getSiteConfig()返回 siteConfig 的深拷贝L94-L96reset(config siteConfig)清空 directives把 currentConfig 重置为给定配置默认 siteConfigL194-L198setConfig(conf)已废弃deprecated只更新 currentConfig且会被下一次addDirective/reset覆盖L106-L110reset的语义就是文档中protected承诺的落地Calls to reset will reset thecurrentConfigtositeConfig。Configuration 文档 进一步说明每次渲染图表前Mermaid 都会在最早期调用reset回到站点基线从而保证不同图之间配置互不串扰。config.spec.ts#L89-L101 验证了setSiteConfig → setConfig → reset → 回到站点值的完整往返。此外 packages/mermaid/src/diagram-api/diagramAPI.ts 内部重新导出了setSiteConfig供各图表模块测试使用例如 sequenceDiagram.spec.js#L1885 中用setSiteConfig({ logLevel: 5, sequence: conf })注入序列图配置。八、实践要点清单站点配置只在应用初始化时设置一次通过initializesetSiteConfig每调用一次都是回到默认值再重新合并反复调用不会累积。需要增量微调站点配置时用updateSiteConfig避免重复传递全量配置。读取配置getSiteConfig()取站点基线getConfig()取当前生效配置均为深拷贝。getConfig的 JSDoc 建议避免反复调用应将结果存入变量并向下传递config.ts#L113-L122。站点所有者要把自定义项也受保护起来应在initialize的secure数组中追加声明图作者侧传入 secure 键、__前缀键或含//url(data:的字符串都会被sanitize就地移除。注意弃用项setConfig已废弃flowchart.htmlLabels应改用全局htmlLabelslazyLoadedDiagrams/loadExternalDiagramsAtStartup应改用registerExternalDiagrams这些都会由checkConfig/ 相关工具函数发出弃用警告。九、延伸阅读API 文档setSiteConfig、MermaidConfig 接口配置模型总览Configuration指令机制与 8.6.0 新 API8.6.0 变更文档配置核心实现config.ts默认配置与 SchemadefaultConfig.ts、config.schema.yaml深合并工具assignWithDepth.ts单元测试config.spec.ts【免费下载链接】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），仅供参考