Linux 依賴套件

在 Linux 系統（包含 CI/CD 環境和 Docker 容器）上執行 Remotion，需要安裝 Chromium 所需的系統依賴套件。若缺少這些套件，Chromium 將無法啟動，導致渲染失敗。

完整套件清單

以下是在 Debian/Ubuntu 系統上所需的套件：

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

各 Linux 發行版的安裝指令

Ubuntu / Debian

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

CentOS / RHEL / Fedora

sudo yum install -y \
  nss \
  dbus-libs \
  atk \
  libgbm \
  alsa-lib \
  libXrandr \
  libxkbcommon \
  libXfixes \
  libXcomposite \
  libXdamage \
  at-spi2-atk \
  cups-libs \
  pango \
  cairo
 
# Fedora 使用 dnf
sudo dnf install -y nss dbus-libs atk mesa-libgbm alsa-lib \
  libXrandr libxkbcommon libXfixes libXcomposite libXdamage \
  at-spi2-atk cups-libs pango cairo

Alpine Linux

Alpine Linux 使用 musl libc，Chromium 的支援較為特殊，建議直接安裝 Chromium：

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

然後在 Remotion 中指定 Chromium 路徑：

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

字體套件

如果你的影片需要顯示特定語言的文字，還需要安裝對應的字體套件：

# 安裝中文字體
apt-get install -y fonts-noto-cjk fonts-noto-cjk-extra
 
# 安裝日文字體
apt-get install -y fonts-noto-cjk
 
# 安裝阿拉伯文字體
apt-get install -y fonts-noto-arabic
 
# 安裝表情符號字體
apt-get install -y fonts-noto-color-emoji

使用 Remotion 提供的安裝腳本

Remotion 提供了一個方便的腳本，可以自動安裝所有必要的依賴：

# 查看需要安裝哪些套件
npx remotion browser ensure --check
 
# 自動安裝（需要 sudo 權限）
sudo npx remotion browser install-deps

在 GitHub Actions 中

name: Render Video
 
on: [push]
 
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "20"
 
      - name: Install dependencies
        run: npm install
 
      - name: Install Chrome dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libnss3 libdbus-1-3 libatk1.0-0 libgbm-dev \
            libasound2 libxrandr2 libxkbcommon-dev libxfixes3 \
            libxcomposite1 libxdamage1 libatk-bridge2.0-0 \
            libcups2 libpango-1.0-0 libcairo2
 
      - name: Ensure Chrome Headless Shell
        run: npx remotion browser ensure
 
      - name: Render video
        run: npx remotion render MyComp out/video.mp4

錯誤診斷

若 Chromium 啟動失敗，常見的錯誤訊息與解決方式：

錯誤訊息	可能原因	解決方式
`libnss3.so: cannot open shared object file`	缺少 NSS 函式庫	`apt-get install libnss3`
`libgbm.so.1: cannot open shared object file`	缺少 GBM 函式庫	`apt-get install libgbm-dev`
`error while loading shared libraries: libasound.so.2`	缺少 ALSA 函式庫	`apt-get install libasound2`
`No usable sandbox`	沙箱設定問題	加入 `--no-sandbox` 旗標

小結

在 Linux 上執行 Remotion 前，必須安裝 Chromium 的系統依賴套件。
Debian/Ubuntu 使用 apt-get，CentOS/RHEL 使用 yum，Alpine 直接安裝 chromium。
若需顯示非拉丁語系文字，額外安裝 fonts-noto-cjk 等字體套件。
在 CI/CD 中，將套件安裝步驟加入工作流程設定檔。