Chromium 旗標

Remotion 在渲染影片時，會啟動 Chromium（或 Chrome Headless Shell）並傳入一系列旗標（flags）來控制瀏覽器行為。理解這些旗標有助於排查問題，並在特殊環境中進行自訂設定。

Remotion 預設使用的旗標

Remotion 在啟動 Chromium 時，會自動加入以下旗標（視環境而定）：

旗標	用途
`--no-sandbox`	在 Docker 容器中必須停用沙箱
`--disable-setuid-sandbox`	同上，避免 setuid 沙箱問題
`--disable-dev-shm-usage`	防止 /dev/shm 空間不足導致崩潰
`--disable-gpu`	在無顯示器環境中停用 GPU 加速
`--headless`	以無頭模式執行，不顯示視窗
`--hide-scrollbars`	隱藏捲軸，避免出現在截圖中
`--mute-audio`	靜音，避免渲染時播放聲音

自訂 Chromium 旗標

你可以透過 chromiumOptions 傳入自訂旗標：

import { renderMedia, selectComposition } from "@remotion/renderer";
 
await renderMedia({
  composition,
  serveUrl,
  codec: "h264",
  outputLocation: "out/video.mp4",
  chromiumOptions: {
    disableWebSecurity: true,           // 停用 CORS 限制（開發用途）
    ignoreCertificateErrors: true,      // 忽略 SSL 憑證錯誤
    headless: true,                     // 無頭模式（預設）
    gl: "angle",                        // 指定 OpenGL 後端
    userAgent: "MyCustomAgent/1.0",     // 自訂 User-Agent
  },
});

透過 CLI 傳入旗標

在指令列中，可以用 --chromium-flags 選項傳入額外旗標：

npx remotion render MyComp out/video.mp4 \
  --chromium-flags="--disable-web-security --allow-running-insecure-content"

注意：多個旗標以空格分隔，整個值用引號包住。

remotion.config.ts 設定

也可以在設定檔中永久設定 Chromium 選項：

// remotion.config.ts
import { Config } from "@remotion/cli/config";
 
Config.setChromiumOpenGlRenderer("angle");
Config.setChromiumDisableWebSecurity(false);
Config.setChromiumIgnoreCertificateErrors(false);
Config.setChromiumHeadlessMode(true);

常見情境與對應旗標

在 Docker 中執行

Docker 容器通常沒有 setuid 能力，必須停用沙箱：

chromiumOptions: {
  // Remotion 在 Docker 中會自動處理，通常不需手動設定
}

Remotion 會自動偵測 Docker 環境並加入必要旗標。

解決字體渲染問題

若在 Linux 上渲染時字體顯示不正確：

npx remotion render MyComp out/video.mp4 \
  --chromium-flags="--font-render-hinting=none"

啟用特定網頁功能

某些實驗性的 Web API 需要額外旗標才能使用：

chromiumOptions: {
  // 停用 web security 以允許跨來源請求（僅開發環境）
  disableWebSecurity: true,
}

處理大型 Canvas

若影片中使用大型 Canvas 元素，可能需要調整記憶體限制：

--chromium-flags="--max-old-space-size=4096"

偵錯旗標

在開發過程中，可以暫時加入以下旗標來協助除錯：

chromiumOptions: {
  // 啟用詳細日誌
  // 注意：這些旗標會大幅增加輸出量
},

# 查看 Chromium 啟動時使用的完整旗標
REMOTION_LOG=verbose npx remotion render MyComp out/video.mp4

注意事項

某些旗標可能在不同版本的 Chromium 中行為不同。
--no-sandbox 會降低安全性，請勿在不受信任的環境中使用。
自訂旗標可能與 Remotion 內部使用的旗標衝突，若遇到問題請逐一排查。
Remotion Cloud（如 Lambda）環境中，部分旗標可能被忽略或覆寫。