渲染卡住或停止回應

如果您的渲染卡住，請按照以下步驟進行排查：

1. 檢查長時間執行的 delayRender() 呼叫

如果 delayRender() 逾時設定過大且未能解除，渲染可能會無限期卡住，而不會顯示任何錯誤訊息。

在 Remotion Lambda 上更容易混淆

在 Remotion Lambda 上，執行環境本身也有逾時限制。如果 delayRender() 的逾時值大於 Lambda 函數逾時值，Lambda 函數會先超時，而 delayRender() 呼叫不會先失敗，導致沒有顯示任何錯誤訊息。

除錯步驟

設定較小的 delayRender() 逾時值，這樣如果未解除，就會顯示錯誤訊息：

import { delayRender } from "remotion";
 
// 設定較短的逾時時間以便除錯
const handle = delayRender("載入資料", {
  timeoutInMilliseconds: 5000, // 5 秒後顯示錯誤
});

始終使用 cancelRender() 處理錯誤，確保在無法呼叫 continueRender() 時能夠中止渲染：

import { delayRender, continueRender, cancelRender } from "remotion";
 
const handle = delayRender("載入資料");
 
fetchData()
  .then((data) => {
    // 處理資料
    continueRender(handle);
  })
  .catch((err) => {
    cancelRender(err); // 發生錯誤時取消渲染
  });

2. 啟用詳細日誌記錄

啟用詳細日誌記錄以查看瀏覽器或其他子程序的任何失敗情況：

npx remotion render --log=verbose

或在程式碼中：

await renderMedia({
  composition,
  serveUrl,
  codec: "h264",
  outputLocation,
  logLevel: "verbose",
});

詳細日誌會顯示：

• 瀏覽器內部的 JavaScript 錯誤
• 網路請求的狀態
• 幀渲染的計時資訊

3. 確保使用 Chrome Headless Shell

較新版本的 Chrome 可能與 Remotion 不相容，並導致渲染卡住，因為它們已移除 Headless 模式。您需要改用 Chrome Headless Shell。

注意： 此問題不會發生在 Remotion Lambda 上。

最佳實踐

• 不要從 Linux 套件管理器下載 Chrome
• 不要設定 --chrome-executable 選項，讓 Remotion 自動下載相容版本的 Chrome Headless Shell
• 在首次渲染前，使用以下指令確保相容版本的 Chrome Headless Shell 已就緒：

npx remotion browser ensure

此指令會自動下載並驗證正確版本的 Chrome Headless Shell。

確認使用的 Chrome 版本

npx remotion browser info

4. Lambda：您是否在讀取 errors 欄位？

如果 Lambda 上的 overallProgress 欄位卡住，請確認您：

正在讀取 errors 欄位以查看是否有任何錯誤：

import { getRenderProgress } from "@remotion/lambda";
 
const progress = await getRenderProgress({
  renderId,
  bucketName,
  functionName,
  region,
});
 
// 檢查是否有錯誤
if (progress.errors && progress.errors.length > 0) {
  console.error("渲染錯誤：", progress.errors);
}
 
// 如果遇到致命錯誤，停止輪詢
if (progress.fatalErrorEncountered) {
  console.error("發生致命錯誤，停止輪詢");
  return;
}

在 fatalErrorEncountered 為 true 時，不要繼續輪詢 getRenderProgress()。

常見卡住場景及解決方法

相關資源

• delayRender() 文件
• cancelRender() 文件
• Chrome Headless Shell 設定
• 除錯逾時問題