看到Failed to set up Chromium r1108766!这行红色报错的时候我正在给一台新电脑装 mermaid-cli。老实说这不是我第一次被 puppeteer 卡住了但我敢打赌凡是用npm install -g mermaid-js/mermaid-cli装过这个工具的人十个里面有八个都在同一条阴沟里翻过船。这篇文章把我这次排错的过程完整记录下来——从报错原因、环境检查到几种能落地的解决方案最后再附一份安装完成后的常用操作和避坑清单。不管你是 Windows、macOS 还是 Linux 用户照着走一遍大概率就能把 mermaid-cli 跑起来。前半部分讲原理给没接触过 puppeteer 的新手看不想看原理、只求救命的直接跳到第三节看解决方案。1. 先搞明白装一个绘图工具为什么还要下载浏览器1.1 mermaid-cli 的工作原理Mermaid 是一种用文本描述图表的语法比如下面这段graph TD A[开始] -- B{判断} B --|是| C[输出结果] B --|否| D[结束]这段文本可以渲染成流程图、时序图、甘特图、饼图等常见图表类型。而 mermaid-cli安装后命令名是mmdc的作用就是在命令行里把这类文本渲染成 PNG、SVG、PDF 文件方便写技术文档、做自动化脚本、接入 CI 流水线。但问题来了Mermaid 的渲染核心是跑在浏览器里的。mermaid-cli 并没有自己内置一个浏览器渲染器它选择的是用 puppeteer 这个 Node 库去驱动一个无头浏览器把所有绘图逻辑在浏览器环境里执行完毕后截取成图。所以你装 mermaid-cli 的时候npm 拉完主包之后还要执行 puppeteer 的安装脚本把配套的 Chromium 下载到本机缓存目录里。这一步一旦失败就是开头那个报错。1.2 报错信息里藏着哪些线索报错原文是Failed to set up Chromium r1108766!。其中r1108766是 puppeteer 锁定的一组 Chromium 构建编号revision它不是随便给的而是跟 puppeteer 的版本严格对应。puppeteer 每个版本都绑定一个 Chromium 构建这样可以保证自动化行为的一致性。但这也意味着如果你手动去网上下载一个别的 Chromium放到缓存目录里但版本对不上一样会报错。这个报错的本质是puppeteer 的安装脚本需要去境外存储服务下载 Chromium 压缩包下载动作发生在 npm 安装包的 postinstall 阶段。一旦下载失败npm 就会把 puppeteer 安装脚本的报错原样抛出来——也就是你看到的这行红字。报错前面通常还会有一行更具体的错误原因常见的有这几种ETIMEDOUT连接下载地址超时网络请求迟迟得不到响应。ENOTFOUND/getaddrinfoDNS 解析失败压根找不到下载服务器的 IP。ECONNREFUSED连接被直接拒绝常见于公司代理或防火墙环境。磁盘相关错误缓存目录不可写或者磁盘满了。2. 动手排错前先做一轮环境体检2.1 确认 Node 和 npm 版本别让旧版本添乱在纠结 Chromium 之前先确认一下基础环境。请在终端执行node -v npm -vNode 版本建议至少 16 以上npm 版本建议 8 以上。新版 puppeteer 对 Node 版本有要求如果 Node 太老会报出各种奇怪的语法错误很容易把排查方向带偏。顺便看一下 npm 当前用的镜像源npm config get registry如果你之前已经换过淘宝镜像会显示https://registry.npmmirror.com/如果显示的是官方源https://registry.npmjs.org/网络环境又不太稳定的话建议先换源再继续。换源命令是npm config set registry https://registry.npmmirror.com注意这一步只影响 npm 包本身的下载速度不影响 puppeteer 下载 Chromium。Chromium 的下载走的是另一条路后面第三节会说。2.2 Windows 用户先解决 PowerShell 脚本执行策略很多 Windows 新手在这一步就卡住了不是在下载 Chromium而是 npm 命令根本跑不起来——报错是npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这是因为 PowerShell 默认的执行策略是 Restricted不允许运行 .ps1 脚本。解决办法有两种第一种临时在当前窗口放开限制Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass第二种永久放开当前用户的限制推荐Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned之后重新打开终端再执行 npm 命令就好了。2.3 验证下载地址到底通不通在换任何方案之前建议先手动验证一下 Chromium 的下载链路。新版 puppeteer 的 Chromium 下载地址大致长这样https://storage.googleapis.com/chrome-for-testing-public/...你可以直接用浏览器访问这个域名看看能不能打开。如果浏览器打不开或者一直转圈那基本可以确定是网络层面的问题靠重试是解决不了的。这时候就可以直接进入下一节的解决方案了。如果你在公司网络环境还要确认一下 npm 和 puppeteer 的代理设置。npm 的代理可以在.npmrc里配置puppeteer 的下载也一样走系统代理如果代理配置不对同样会导致下载失败。3. 三种能落地的解决方案照着抄就行3.1 方案一给 puppeteer 指定国内下载镜像这是最推荐、也是大多数场景下最省事的办法。既然 Chromium 从官方存储服务器下载不通那就让 puppeteer 去国内镜像下载本质就是设置一个环境变量PUPPETEER_DOWNLOAD_BASE_URL。先确认 mermaid-cli 里 puppeteer 的大版本。可以通过下面命令查看npm view mermaid-js/mermaid-cli dependencies如果 puppeteer 版本是 19 及以上主流的 mermaid-cli 已经是这个范围使用 Chrome for Testing 的新下载路径镜像地址设置为https://cdn.npmmirror.com/binaries/chrome-for-testing如果 puppeteer 版本较旧则使用老的 Chromium 快照镜像地址https://npmmirror.com/mirrors/chromium-browser-snapshots设置方式按系统分macOS / Linuxexport PUPPETEER_DOWNLOAD_BASE_URLhttps://cdn.npmmirror.com/binaries/chrome-for-testing npm install -g mermaid-js/mermaid-cliWindows PowerShell$env:PUPPETEER_DOWNLOAD_BASE_URLhttps://cdn.npmmirror.com/binaries/chrome-for-testing npm install -g mermaid-js/mermaid-cli如果不确定 puppeteer 版本有个更省事的方法——直接把镜像地址写到 npm 配置里转发给 puppeteer 的安装脚本。执行npm config set puppeteer_download_base_url https://cdn.npmmirror.com/binaries/chrome-for-testing然后重新安装npm install -g mermaid-js/mermaid-cli这里要说明一下npm config set会把配置写进当前用户的.npmrc文件puppeteer 的安装脚本会读取 npm config 里的相关键值。实测这个方式是有效的而且不用每次开终端都重新设置环境变量。安装过程看到进度条在走动、速度正常的 Chromium 下载进度就代表镜像生效了。3.2 方案二不下载 Chromium直接用系统自带的浏览器如果你机器上已经装了 Chrome、Edge 或其他 Chromium 内核浏览器完全可以跳过 Chromium 的下载步骤让 puppeteer 直接调用系统浏览器来渲染。这个方案有两个好处一是安装速度快很多二是避免了大体积浏览器包占磁盘空间。先设置跳过下载export PUPPETEER_SKIP_DOWNLOADtrue # Windows PowerShell 用: # $env:PUPPETEER_SKIP_DOWNLOADtrue然后正常安装npm install -g mermaid-js/mermaid-cli这时候 mermaid-cli 能装上但如果直接运行mmdc会提示找不到浏览器。需要一个配置文件告诉 puppeteer 系统浏览器在哪里。在你想运行mmdc命令的工作目录下新建一个.puppeteerrc.cjs文件内容类似这样module.exports { executablePath: /usr/bin/google-chrome, };Windows 系统的路径一般是module.exports { executablePath: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe, };如果你用的是微软 Edge路径是module.exports { executablePath: C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe, };macOS 的 Chrome 路径是module.exports { executablePath: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome, };这里有一个关键细节mermaid-cli 读取配置文件时是在当前工作目录里寻找.puppeteerrc.cjs的。也就是说你在哪个目录下执行mmdc就要保证那个目录里有这个配置文件。如果你希望全局都能用可以把配置文件放到用户主目录下这样默认也能找到。注意PUPPETEER_SKIP_DOWNLOAD只跳过下载不会跳过 puppeteer 包本身的安装。如果你用方案二一定要确认配置文件里的浏览器路径是真实存在的否则运行时还是会报 Could not find Chrome 之类的错误。3.3 方案三手动下载 Chromium塞进本地缓存这个方案适合完全没有外网、只能靠内网传输文件的离线环境也适合那些因为下载断断续续导致缓存文件损坏的场景。先检查 puppeteer 的缓存目录位置。默认情况下Windows 是在%USERPROFILE%\.cache\puppeteermacOS / Linux 是在~/.cache/puppeteer。你可以通过环境变量PUPPETEER_CACHE_DIR自定义缓存目录位置。然后去镜像站手动下载对应 revision 的 Chromium 压缩包。以 r1108766 为例新版路径一般类似https://cdn.npmmirror.com/binaries/chrome-for-testing/r1108766/win64/chrome-win64.zip平台不同路径里的win64、linux64、mac-arm64要对应改。把压缩包下载回来后解压到 puppeteer 缓存目录下并且目录结构要符合 puppeteer 的预期——它会按照cache_dir/chrome/platform/buildId的方式去寻找浏览器可执行文件。这个方案对手工操作的要求比较高目录结构一旦不对puppeteer 就不认。一个更省事的方式是在一台能联网的机器上装好 mermaid-cli然后把整个 puppeteer 缓存目录打包拷贝到离线机器上再同步设置PUPPETEER_CACHE_DIR指向这个目录。这样目录结构绝对不会错。3.4 全局装还是项目内装这个问题值得多说几句。虽然标题是全局安装但实际使用中我更推荐在项目内安装mkdir mermaid-demo cd mermaid-demo npm init -y npm install mermaid-js/mermaid-cli项目内安装的好处主要有三点版本可控。mermaid-cli 更新频繁全局装的话哪天npm update -g就可能把版本升了图表渲染行为跟着变。项目内安装则把版本锁定在 package.json 里。依赖不冲突。mermaid-cli 依赖的 puppeteer 版本可能跟你项目里其他依赖的 puppeteer 版本不一致全局装容易造成混乱。配置好管理。.puppeteerrc.cjs放在项目根目录跟着仓库走团队协作时大家拿到的配置完全一致。当然如果你只是偶尔在某个目录下用一下全局安装确实方便装完之后命令行直接敲mmdc就能用。两种方式没有绝对对错看你的使用频率。如果你用 pnpm 管理项目全局安装的命令会有点区别但 mermaid-cli 本身在 pnpm 下的使用方式是一样的这里就不展开了。4. 装好之后验证、日常使用与高频问题4.1 第一次渲染验证安装完成后先确认命令能用mmdc --version能打印出版本号说明安装基本成功。接下来写一个测试文件test.mmdsequenceDiagram participant A as 用户 participant B as 服务端 A-B: 发送请求 B--A: 返回结果然后执行渲染mmdc -i test.mmd -o test.png -w 800 -b white如果输出了一张时序图恭喜你整套链路已经通了。mermaid-cli 的常用参数有这些参数作用示例-i输入文件-i input.mmd-o输出文件-o output.png-w输出图片宽度-w 1024-b背景色-b white-s缩放倍数-s 2-t主题-t dark-f输出 PDF 格式-f这里重点说一下-s参数也就是缩放。很多人在导出高清图时踩过坑明明-w 1000设置了宽度但出来的图还是模糊。其实 mermaid-cli 里-s才是控制最终分辨率的关键。比如你要生成一张 2 倍分辨率的图mmdc -i input.mmd -o output.png -s 2如果是在服务器或者 Docker 容器里跑浏览器会因为缺少权限启动失败这时候需要在.puppeteerrc.cjs里加上--no-sandboxmodule.exports { args: [--no-sandbox, --disable-setuid-sandbox], };4.2 常见问题速查表我自己在排错过程中以及日常帮同事处理问题时整理过一张速查表这里直接分享出来。现象根本原因解决办法Failed to set up Chromium rxxxChromium 下载失败设置PUPPETEER_DOWNLOAD_BASE_URL指向镜像npm.ps1无法加载PowerShell 执行策略限制Set-ExecutionPolicy RemoteSignednpm不是内部或外部命令Node 没加入 PATH重新安装 Node 并勾选 Add to PATHERR! code ERESOLVEpeer 依赖冲突加--legacy-peer-deps重试ERR! code EBUSY文件被占用Windows 常见关闭 Node 进程和杀软重试warn deprecated node-domexception1.0.0依赖的依赖被弃用不影响使用忽略即可找不到 Chrome / executablePath 报错puppeteer 没找到浏览器配置.puppeteerrc.cjs指定路径EUNSUPPORTEDPROTOCOLnpm 版本太老升级 npm或换 pnpm 处理 workspace 协议gyp verb check pythonnode-gyp 需要编译工具链安装 Python 和 C 构建工具4.3 几个容易被忽略的 npm 小细节安装过程中你可能会看到一些吓人的警告但很多其实无害。比如npm warn deprecated node-domexception1.0.0: use your platforms native dome这是 npm 在提醒某个底层依赖已经被弃用属于传递依赖的警告跟你的项目代码没关系可以安全忽略。再比如ERR! code ERESOLVE overriding peer dependency这是 npm 7 之后严格 peer 依赖检查导致的。如果某个包跟 mermaid-cli 的依赖有冲突可以先试试npm install -g mermaid-js/mermaid-cli --legacy-peer-deps如果还不行最好检查一下本地是不是有多个 Node 版本混用。我见过有人用 nvm 切换版本后全局包路径对不上结果 npm 安装到一个 Node 版本、运行命令时用的却是另一个版本这种问题排查起来非常耗时间。最后提一下npm ci和npm i的区别npm ci会严格按照 lockfile 安装不会改版本适合 CI 环境npm i会检查并可能更新依赖。在项目内安装 mermaid-cli 后如果提交过 package-lock.json团队成员拉下来用npm ci安装就能保证环境一致。5. 最后分享两个小技巧在整个排错过程中我最后形成了自己的一套组合拳这里分享出来。如果你也在网络受限的环境下工作可以试试先设置 npm 镜像再设置 puppeteer 下载镜像最后用一个快速的 Chrome 路径判断来兜底npm config set registry https://registry.npmmirror.com npm config set puppeteer_download_base_url https://cdn.npmmirror.com/binaries/chrome-for-testing npm install -g mermaid-js/mermaid-cli这套配置写进.npmrc后基本一劳永逸之后不管是装 mermaid-cli 还是其他依赖 puppeteer 的工具都不会再被 Chromium 下载问题卡住。另一个小技巧是不要把 mermaid-cli 当成一个只装一次就完事的工具。它的版本更新很快Mermaid 语法也在持续演进建议隔一段时间就主动升级一次避免文档里的新语法在你本地渲染不出来。升级命令很简单npm update -g mermaid-js/mermaid-cli如果在公司内网环境没法访问外网镜像那就在内网搭一个 npm 私有仓库把puppeteer_download_base_url指到内网同步好的 Chromium 镜像地址。这个方案维护成本稍高但对于团队来说是最稳定的做法。
