Chrome Headless Shell

Remotion 需要一個 Chromium 瀏覽器實例來渲染每一幀影片。從 Chrome 112 開始，Google 將「Headless Chrome」拆分為獨立的二進位檔案，稱為 Chrome Headless Shell。

什麼是 Chrome Headless Shell？

Chrome Headless Shell 是 Chromium 的精簡版本，專為自動化測試與伺服器端渲染設計：

不包含完整 UI：沒有瀏覽器工具列、分頁等介面元素。
體積更小：比完整的 Chrome 瀏覽器小約 50%。
啟動更快：減少不必要的初始化步驟。
更適合伺服器：針對無顯示器環境最佳化。

Remotion 如何取得 Chrome Headless Shell

自動下載（推薦）

Remotion 提供了 @remotion/install-headless-chrome 套件，可以自動下載適合當前系統的 Chrome Headless Shell：

npx remotion browser ensure

或者在 CI/CD 流程中：

npm install
npx remotion browser ensure

這個指令會：

偵測目前的作業系統和架構
下載對應版本的 Chrome Headless Shell
將其存放在 Remotion 的快取目錄中

使用系統已安裝的 Chrome

若系統中已安裝 Chrome 或 Chromium，Remotion 會自動偵測並使用。你也可以明確指定路徑：

import { renderMedia } from "@remotion/renderer";
 
await renderMedia({
  composition,
  serveUrl,
  codec: "h264",
  outputLocation: "out/video.mp4",
  browserExecutable: "/usr/bin/google-chrome",
});

或透過環境變數：

BROWSER_EXECUTABLE=/usr/bin/chromium-browser npx remotion render MyComp out/video.mp4

支援的平台

Chrome Headless Shell 支援以下平台：

平台	架構	支援狀態
macOS	x64 (Intel)	支援
macOS	arm64 (Apple Silicon)	支援
Linux	x64	支援
Linux	arm64	支援
Windows	x64	支援

版本管理

Remotion 會追蹤並使用特定版本的 Chrome Headless Shell，以確保渲染結果的一致性。查看目前使用的版本：

npx remotion browser version

若需要更新到最新版本：

npx remotion browser ensure --force

在 Docker 中使用

在 Docker 容器中，建議在 Dockerfile 中加入安裝步驟：

FROM node:20-bookworm-slim
 
# 安裝 Chrome Headless Shell 的系統依賴
RUN apt-get update && apt-get install -y \
  ca-certificates \
  fonts-liberation \
  libasound2 \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libc6 \
  libcairo2 \
  libcups2 \
  libdbus-1-3 \
  libgbm1 \
  libnss3 \
  libxcomposite1 \
  libxdamage1 \
  libxrandr2 \
  wget \
  && rm -rf /var/lib/apt/lists/*
 
WORKDIR /app
COPY package*.json ./
RUN npm install
 
# 下載 Chrome Headless Shell
RUN npx remotion browser ensure
 
COPY . .
CMD ["npx", "remotion", "render", "MyComp", "out/video.mp4"]

快取位置

Chrome Headless Shell 下載後會存放在：

作業系統	快取路徑
macOS	`~/Library/Caches/remotion/chrome`
Linux	`~/.cache/remotion/chrome`
Windows	`%LOCALAPPDATA%\remotion\chrome`

常見問題

下載失敗

若在受限網路環境中下載失敗，可以手動下載後指定路徑：

# 先手動下載 Chrome Headless Shell，然後設定路徑
BROWSER_EXECUTABLE=/path/to/chrome npx remotion render MyComp out/video.mp4

執行權限問題

在 Linux 上，確保二進位檔有執行權限：

chmod +x ~/.cache/remotion/chrome/chrome

ARM Linux 支援

在 ARM 架構的 Linux（如 Raspberry Pi）上，可能需要額外的設定。建議使用 --gl=swiftshader 旗標：

npx remotion render MyComp out/video.mp4 --gl=swiftshader

小結

Chrome Headless Shell 是 Remotion 渲染影片的核心工具。
使用 npx remotion browser ensure 自動安裝。
在 Docker 中需預先安裝所需的系統依賴。
可透過 BROWSER_EXECUTABLE 或 browserExecutable 選項指定自訂路徑。