Remotion LabRemotion Lab
›疑難排解›無法確定可執行檔

無法確定可執行檔

排解 Remotion 中「Could not determine executable to run」錯誤，了解 Chromium 二進位檔無法找到時的原因與修復方式。

無法確定可執行檔

錯誤訊息

Error: Could not determine executable to run.

或類似的變體：

Could not find a Chromium executable to launch.

Browser executable not found at the expected path.

錯誤發生的時機

此錯誤在 Remotion 嘗試啟動 Chromium 瀏覽器以進行渲染時發生，通常出現於：

  • 執行 renderMedia()、renderStill() 等渲染 API 時
  • 執行 npx remotion render 或 npx remotion still 時
  • 在 Docker 容器或 CI/CD 環境中執行渲染時
  • 在 AWS Lambda 或其他無伺服器環境中執行時

原因分析

Remotion 的渲染流程需要啟動一個 Chromium 瀏覽器實例來截圖每一幀。若 Remotion 找不到可執行的 Chromium 二進位檔，就會拋出此錯誤。

解決方案

方案一：讓 Remotion 自動下載 Chromium

Remotion 提供自動下載 Chromium 的指令。在首次使用前執行：

npx remotion browser ensure

此指令會下載適合當前平台的 Chromium 版本，並將其放置在 Remotion 預期的路徑中。

方案二：指定 Chromium 路徑

若你的系統上已安裝 Chromium 或 Chrome，可以明確指定路徑：

CLI：

npx remotion render MyComposition out/video.mp4 \
  --browser-executable=/path/to/chromium

Node.js API：

import { renderMedia, selectComposition } from '@remotion/renderer';
 
await renderMedia({
  composition,
  serveUrl,
  codec: 'h264',
  outputLocation: 'out/video.mp4',
  browserExecutable: '/path/to/chromium',
});

常見的 Chromium / Chrome 路徑：

# macOS - Google Chrome
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
 
# macOS - Chromium
/Applications/Chromium.app/Contents/MacOS/Chromium
 
# Linux - Chromium
/usr/bin/chromium-browser
/usr/bin/chromium
 
# Linux - Google Chrome
/usr/bin/google-chrome
/usr/bin/google-chrome-stable

方案三：在 Docker 環境中安裝 Chromium

在 Docker 中執行 Remotion 時，需要在映像中安裝必要的系統依賴。

以下是適用於 Debian/Ubuntu 基礎映像的 Dockerfile 範例：

FROM node:18-slim
 
# 安裝 Chromium 所需的系統依賴
RUN apt-get update && apt-get install -y \
  chromium \
  fonts-liberation \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libc6 \
  libcairo2 \
  libcups2 \
  libdbus-1-3 \
  libexpat1 \
  libfontconfig1 \
  libgcc-s1 \
  libgdk-pixbuf2.0-0 \
  libglib2.0-0 \
  libgtk-3-0 \
  libnspr4 \
  libnss3 \
  libpango-1.0-0 \
  libpangocairo-1.0-0 \
  libx11-6 \
  libx11-xcb1 \
  libxcb1 \
  libxcomposite1 \
  libxcursor1 \
  libxdamage1 \
  libxext6 \
  libxfixes3 \
  libxi6 \
  libxrandr2 \
  libxrender1 \
  libxss1 \
  libxtst6 \
  --no-install-recommends \
  && rm -rf /var/lib/apt/lists/*
 
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
 
CMD ["node", "render.js"]

在 render.js 中指定 Chromium 路徑：

import { renderMedia, selectComposition } from '@remotion/renderer';
 
await renderMedia({
  composition,
  serveUrl,
  codec: 'h264',
  outputLocation: 'out/video.mp4',
  browserExecutable: '/usr/bin/chromium',
});

完整的 Docker 設定說明請參閱 Docker 文件。

方案四：Lambda 環境

在 AWS Lambda 中，Remotion 使用 @remotion/lambda 套件，它包含了預先配置的 Chromium。若你在 Lambda 上遇到此錯誤，請確認：

  • 使用的是 @remotion/lambda 套件而非通用的 @remotion/renderer
  • Lambda 函式的記憶體配置足夠（建議至少 2048 MB）
  • 使用了官方支援的 Node.js runtime（Node.js 18.x 或 20.x）

方案五：確認二進位檔案權限

若 Chromium 二進位檔案存在但無法執行，可能是權限問題：

# 找到 Chromium 二進位檔
find ~/.cache/puppeteer -name "chrome" -o -name "chromium" 2>/dev/null
 
# 賦予執行權限
chmod +x /path/to/chromium

在 CI/CD 環境中的注意事項

GitHub Actions、GitLab CI 等環境通常沒有預裝 Chromium。有以下幾種做法：

選項一：在 CI 中下載 Chromium

# GitHub Actions 範例
- name: 確保 Chromium 已安裝
  run: npx remotion browser ensure

選項二：使用 Puppeteer 的 GitHub Action

某些 CI 平台提供預裝 Chromium 的 runner，可直接使用。

選項三：使用 Lambda 或 Cloud Run 進行雲端渲染

將渲染任務移至雲端，避免在 CI 中管理 Chromium 安裝。

相關資源