mermaid.cli排错指南Failed to launch chrome、--no-sandbox与全局安装失败的完整解决方案【免费下载链接】mermaid.cliDevelopment has been moved to https://github.com/mermaid-js/mermaid-cli项目地址: https://gitcode.com/gh_mirrors/me/mermaid.climermaid.cli是 mermaid 图表库的命令行工具只需一条mmdc命令就能把.mmd文本文件渲染成 SVG、PNG 或 PDF 图片非常适合文档自动化。新手最常卡在两个坑Linux 下报Failed to launch chrome和全局安装失败。本文是一份完整排错指南带你逐个击破这两个问题。 先搞懂原理mmdc 为什么会启动 Chrome很多人以为 mermaid.cli 只是纯文本转换工具其实不然。看它的核心依赖 package.jsondependencies: { chalk: ^2.4.1, commander: ^2.15.1, puppeteer: ^1.4.0 }它依赖puppeteer每次执行mmdc时入口脚本 index.js 都会通过puppeteer.launch()在后台启动一个真实的Chromium 浏览器加载内置页面 index.html注入 mermaid 渲染引擎把.mmd内容画出来再截图导出。 关键结论只要 Chromium 启动环节出问题mmdc就会失败。而 Linux 上 Chromium 的沙箱sandbox机制正是Failed to launch chrome报错的元凶。 全局安装失败的 3 个解决方案官方 README 明确不推荐全局安装YARN 和 NPM 都可能因为奇怪的权限问题导致全局安装失败。按推荐程度排序方案一本地安装官方首选 ✅在任意项目目录下安装通过相对路径调用mmdcnpm install mermaid.cli ./node_modules/.bin/mmdc -h或使用 Yarnyarn add mermaid.cli ./node_modules/.bin/mmdc -h这种方式绕开了全局目录的权限问题也是 CI/CD 流水线里的标准做法。方案二修正全局安装命令如果你坚持要全局可用命令本身要写对package.json 的bin字段定义了mmdc命令指向打包产物index.bundle.jsnpm install -g mermaid.cli # 或 yarn global add mermaid.cli方案三解决权限问题的根因全局安装报EACCES、permission denied时通常不是包的问题而是 npm 全局目录不可写。推荐的做法用 nvmNode 版本管理器管理 Node全局包会装进用户目录天然没有权限问题避免用sudo npm install -g这类以管理员强行写入系统目录的临时手段后续升级极易再踩坑若仍失败检查npm config get prefix指向的目录当前用户是否有写权限。 报错一Running as root without --no-sandbox在 Linux尤其是 Docker 容器中以 root 运行mmdc你会看到UnhandledPromiseRejectionWarning: Error: Failed to launch chrome! [ERROR:zygote_host_impl_linux.cc] Running as root without --no-sandbox is not supported.原因Chromium 出于安全考虑禁止 root 用户直接运行沙箱。官方建议见 README.md 的 Linux sandbox issue 一节不要以 root 身份运行改用普通用户将 Linux 内核升级到较新版本。 报错二No usable sandbox另一种常见报错UnhandledPromiseRejectionWarning: Error: Failed to launch chrome! [FATAL:zygote_host_impl_linux.cc] No usable sandbox! Update your kernel ... you can try using --no-sandbox.原因当前内核版本较老缺少 Chromium 沙箱所需的内核特性常见于老版 CentOS/Ubuntu 和精简版容器镜像。✅ 一劳永逸用 --no-sandbox 彻底关闭沙箱如果暂时无法升级内核或放弃 root官方给出了最直接的方案——给 Puppeteer 传一个--no-sandbox启动参数。第 1 步在项目里新建puppeteer-config.json{ args: [--no-sandbox] }第 2 步通过-p--puppeteerConfigFile参数传给mmdcmmdc -p puppeteer-config.json -i input.mmd -o output.svg在 index.js 中可以看到-p参数的处理逻辑文件不存在会直接报Configuration file ... doesnt exist存在则读取并整体传给puppeteer.launch()所以上面这份 JSON 会原样生效。⚠️ 注意-p指的是Puppeteer浏览器配置文件和-cmermaid 图表配置文件如test/config.json里的主题配置不是一回事两者可以同时使用。 验证修复一条命令跑通测试项目自带了测试样例test/flowchart.mmd内容是一个简单的流程图定义graph TD A[Christmas] --|Get money| B(Go shopping) B -- C{Let me think}修复沙箱问题后执行以下命令验证mmdc是否正常出图mmdc -p puppeteer-config.json -i test/flowchart.mmd -o test/output.svg若能生成test/output.svg说明排错完成。再试几个常用选项巩固一下完整选项列表可用mmdc -h查看# 导出 PNG透明背景 mmdc -i test/flowchart.mmd -o output.png -b transparent # 导出 PDF指定 1024x768 页面尺寸 mmdc -i test/sequence.mmd -o output.pdf -w 1024 -H 768 # 切换 forest 主题 mmdc -i test/flowchart2.mmd -o output.svg -t forest 常见报错速查表报错关键词典型场景解决方案Failed to launch chromeRunning as rootLinux 下用 root 运行换普通用户或加--no-sandboxNo usable sandbox内核较老 / 精简容器升级内核或加--no-sandboxEACCES、permission denied全局安装本地安装npm install mermaid.cli或改用 nvmConfiguration file ... doesnt exist-p配置路径写错检查puppeteer-config.json路径输出文件报错扩展名不对输出必须为.svg、.png或.pdf写在最后mermaid.cli 的排错逻辑其实很清晰安装层面优先用本地安装绕开权限问题运行层面的Failed to launch chrome本质是 Chromium 沙箱限制用puppeteer-config.json-p参数传入--no-sandbox即可一步解决。最后提醒mermaid.cli这个 npm 包已不再更新社区开发已迁移到mermaid-js/mermaid-cli新包同样提供mmdc命令排错思路完全通用。本文涉及的排错资料可参考仓库中的 README.md、index.js 与test/目录下的各示例文件test/flowchart.mmd、test/sequence.mmd等动手跑一遍测试用例是最快的验证方式。【免费下载链接】mermaid.cliDevelopment has been moved to https://github.com/mermaid-js/mermaid-cli项目地址: https://gitcode.com/gh_mirrors/me/mermaid.cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考