Remotion LabRemotion Lab
›疑難排解›瀏覽器啟動失敗

瀏覽器啟動失敗

解決渲染時出現「Failed to launch the browser process」錯誤的常見原因與修復方法

錯誤訊息

如果你在渲染時看到以下錯誤：

Failed to launch the browser process!

TROUBLESHOOTING: https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md

這表示 Remotion 使用的 Chromium 瀏覽器無法啟動。

常見原因與解決方案

原因一：缺少共享程式庫（Linux 環境最常見）

在 Linux 系統（包括 Docker 容器、CI/CD 環境）中，Chromium 需要多個系統共享程式庫（shared libraries）才能運行。若這些程式庫不存在，瀏覽器就無法啟動。

症狀： 錯誤訊息中通常包含類似 error while loading shared libraries 或 cannot open shared object file 的提示。

解決方式：

在 Ubuntu/Debian 系統上安裝必要的套件：

sudo apt-get update && sudo apt-get install -y \
  ca-certificates \
  fonts-liberation \
  libappindicator3-1 \
  libasound2 \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libc6 \
  libcairo2 \
  libcups2 \
  libdbus-1-3 \
  libexpat1 \
  libfontconfig1 \
  libgbm1 \
  libgcc1 \
  libglib2.0-0 \
  libgtk-3-0 \
  libnspr4 \
  libnss3 \
  libpango-1.0-0 \
  libpangocairo-1.0-0 \
  libstdc++6 \
  libx11-6 \
  libx11-xcb1 \
  libxcb1 \
  libxcomposite1 \
  libxcursor1 \
  libxdamage1 \
  libxext6 \
  libxfixes3 \
  libxi6 \
  libxrandr2 \
  libxrender1 \
  libxss1 \
  libxtst6 \
  lsb-release \
  wget \
  xdg-utils

在 Alpine Linux 上（常用於 Docker）：

apk add --no-cache \
  chromium \
  nss \
  freetype \
  harfbuzz \
  ca-certificates \
  ttf-freefont

原因二：系統架構或作業系統不符

若 Chromium 二進位檔案是為不同的架構或作業系統編譯的，就無法在目前的環境中執行。

常見情境：

  • 在 ARM64（如 Apple Silicon Mac、AWS Graviton）上執行 x64 版本的 Chromium
  • 在 x64 上執行 ARM64 版本的 Chromium
  • 為不同的 Linux 發行版編譯的 Chromium（例如 Ubuntu 版本在 Alpine 上執行）

解決方式：

  1. 確認目前系統架構：
uname -m
# x86_64 表示 x64
# aarch64 或 arm64 表示 ARM64

  1. 確認 Chromium 二進位檔案的架構相符。

  2. 若使用 Docker，確保基礎映像與目標平台一致：

# 明確指定平台
FROM --platform=linux/amd64 node:18-slim
  1. 若使用 Remotion Lambda，確保 Lambda 的架構設定與部署一致。

原因三：在無頭環境中缺少 Display（Linux）

某些 Chromium 版本在沒有顯示伺服器的環境（如純 SSH 伺服器或某些 CI 環境）中需要 Xvfb。

解決方式：

Remotion 通常以 headless 模式啟動 Chromium，不需要顯示伺服器。若仍出現相關錯誤，可嘗試：

# 確保使用 headless 模式（Remotion 預設啟用）
npx remotion render --headless

使用 --log=verbose 診斷

在渲染指令中加入 --log=verbose 旗標，可以輸出所有瀏覽器進程的詳細日誌，協助定位問題：

npx remotion render src/index.ts MyComposition out/video.mp4 --log=verbose

這會顯示 Chromium 的完整啟動輸出，包括任何錯誤訊息或缺少的程式庫。

Docker 環境建議設定

以下是在 Docker 中運行 Remotion 的建議 Dockerfile 設定：

FROM node:18-slim
 
# 安裝 Chromium 依賴套件
RUN apt-get update && apt-get install -y \
  chromium \
  fonts-noto-color-emoji \
  --no-install-recommends \
  && rm -rf /var/lib/apt/lists/*
 
# 設定 Chromium 可執行路徑（若使用系統 Chromium）
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
 
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
 
CMD ["npx", "remotion", "render", "src/index.ts", "MyComposition", "out/video.mp4"]

CI/CD 環境常見設定

GitHub Actions

- name: Install Chromium dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y chromium-browser
 
- name: Render video
  run: npx remotion render src/index.ts MyComposition out/video.mp4

延伸閱讀