企业官网建设流程全解析

Remotion 启动浏览器报 'Failed to launch the browser process!' 怎么排查？

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion

用 Remotion 渲染视频时（例如执行npx remotion render），如果终端出现如下报错：

Failed to launch the browser process! TROUBLESHOOTING: https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md // or a URL pointing to this page

它表示 Remotion 内部的浏览器进程没能启动。根据 官方排查文档，最常见的原因是两类：缺少共享库（Linux 上）和操作系统或 CPU 架构不匹配。下面按这两条路径给出排查步骤，最后给出官方推荐的调试手段。

第一步：先确认报错形态

先确认你看到的确实是 "Failed to launch the browser process!" 开头的错误，而不是渲染中途因代码异常或内存不足失败——那些属于不同的排查文档。只要报错包含上面这段信息，就按下面的顺序排查。

原因一（Linux）：缺少共享库

在 Linux 上，Chrome Headless Shell 运行前需要安装若干共享库。缺库时浏览器进程会直接启动失败，报出本文的错。

解决方法是按你的发行版安装对应的库。以 Ubuntu 22.04 / 24.04 为例：

apt install -y \ libnss3 \ libdbus-1-3 \ libatk1.0-0 \ libasound2t64 \ libxrandr2 \ libxkbcommon-dev \ libxfixes3 \ libxcomposite1 \ libxdamage1 \ libgbm-dev \ libcups2 \ libcairo2 \ libpango-1.0-0 \ libatk-bridge2.0-0

注意这条命令会向系统安装一组共享库包，属于系统级变更，需要管理员权限（如sudo）。其他发行版请使用 Linux Dependencies 文档中对应版本的命令：

• 较老版本的 Ubuntu：与上面列表相同，但包名是libasound2（不是libasound2t64）。
• Debian：同样是apt install，包列表与 Ubuntu 接近（含libgbm-dev、libasound2等）。
• Amazon Linux 2023：改用yum install，安装mesa-libgbm、nss、alsa-lib、pango等对应包。

两个发行版需要特别注意，它们直接不受支持：

• Alpine Linux：因不支持的 Libc 符号，无法运行。
• nixOS：Remotion 自带 Chrome 和 FFmpeg 的二进制文件，没有烘焙进操作系统，与 nixOS 的 "immutable distro" 架构冲突。

如果你的环境是这两个系统，装库解决不了问题，需要换用受支持的发行版。

原因二：操作系统或 CPU 架构不匹配

如果在 arm64 机器上运行了 x64 的浏览器二进制（或反过来），也会报这个错误。如果浏览器是为另一个操作系统、或另一个 Linux 发行版编译的，同样可能不兼容。

处理方式：确认你使用的浏览器二进制与当前系统的操作系统和 CPU 架构一致，换用匹配当前环境的二进制。在 Apple Silicon 上运行 Remotion 时，官方推荐用原生 arm64 架构的 Node（可用node -p process.arch确认架构是否为arm64），架构错配既影响性能也可能导致启动问题，详见 Apple Silicon under Rosetta 文档。

仍无法定位时：用 --log=verbose 查看浏览器进程输出

如果上面两项都不像根因，官方推荐在渲染命令上加--log=verbose标志：

npx remotion render --log=verbose

该标志会把浏览器进程的全部输出打印出来，用于进一步定位浏览器为什么起不来。排查时观察这些日志，判断是缺库（报错中通常含具体 so 库名，可对照第一步的清单）、架构问题还是其他异常。

排查小结

• Linux + 缺库：按 Linux Dependencies 文档 安装对应发行版的共享库（Alpine、nixOS 不受支持）。
• 架构错配：换用与当前操作系统/CPU 架构匹配的浏览器二进制。
• 拿不准根因：npx remotion render --log=verbose打开浏览器进程完整日志继续分析。

完整说明见 Failed to launch the browser process。

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion