Mermaid流程图中如何嵌入本地图片文件（mermaid-cli场景）

mermaid-cli 底层基于Puppeteer调用无头Chromium完成渲染，仅配置securityLevel: "loose"只会放开Mermaid自身的标签沙箱限制，不会修改Chromium默认的本地文件访问拦截规则，因此直接写磁盘绝对路径、file://协议路径都会出现图片加载失败的问题，以下是两种可直接落地的解决方法：

方案1：相对路径 + 渲染参数放开权限（零额外依赖） #

• 调整文件目录结构，将待嵌入图片与Mermaid源码文件放在同一工作目录下，参考结构：

workspace/
├─ chart.mmd
└─ image.png

• 修改Mermaid源码中的图片引用为相对路径，不要写盘符绝对路径、不要加file://前缀：

%%{init: { "securityLevel": "loose", "flowchart": { "htmlLabels": true } } }%%
flowchart LR;
    A( <img src='image.png' height='200px' width='200px'/> )--> B & C & D;
    B--> A & E;
    C--> A & E;
    D--> A & E;
    E--> B & C & D;

如果图片存放在子目录（比如assets/image.png），src对应写相对路径即可。

• 执行渲染命令时追加Puppeteer启动参数，放开本地文件访问权限：

mmdc -i chart.mmd -o chart_cli.png --puppeteer-args "--allow-file-access-from-files --disable-web-security"

执行命令前需将终端工作目录切换到chart.mmd所在的workspace目录，避免相对路径匹配失败。

方案2：本地静态服务托管资源（兼容性最优） #

如果方案1在当前mermaid-cli版本下不生效，可通过本地临时起静态服务的方式模拟HTTP资源加载，和线上图床的加载逻辑完全一致：

• 在存放Mermaid源码和图片的目录下，启动本地静态服务，无需额外安装工具，使用系统已装的Python即可：
  • Python 3 环境执行：python -m http.server 8080
  • Python 2 环境执行：python -m SimpleHTTPServer 8080
• 修改Mermaid源码中的图片地址为本地服务地址：

A( <img src='http://127.0.0.1:8080/image.png' height='200px' width='200px'/> )

• 执行原有渲染命令即可正常出图，渲染完成后关闭终端的静态服务进程即可。

常见无效写法说明 #

• 直接写Windows盘符绝对路径（如C:/path/image.png）：Mermaid的HTML解析逻辑不会将该格式识别为合法资源地址，无法触发加载。
• 仅添加file://前缀不修改渲染参数：默认配置下Chromium会拦截跨源的本地文件访问，必须搭配--allow-file-access-from-files参数才有可能生效。
• 仅配置securityLevel: "loose"：该配置只负责放开Mermaid对HTML标签的过滤规则，不涉及底层浏览器的安全策略调整，无法单独解决本地文件加载问题。

内容的提问来源于stack exchange，提问作者N Strahl