排解渲染逾時錯誤

錯誤訊息說明

當你在 Remotion 渲染過程中看到以下錯誤：

A delayRender() was called but not cleared after 28000ms.
See https://remotion.dev/docs/timeout for help.
The delayRender was called

這代表某個 delayRender() 呼叫被建立後，從未呼叫對應的 continueRender() 來解除等待。Remotion 在等待截圖前，預設最多會等待 30 秒，超過後會自動中止並拋出此錯誤，避免渲染程序無限掛起。

可能的原因

未呼叫 `continueRender()`

最常見的原因是程式碼中呼叫了 delayRender()，但在某些情況下（例如 Promise 被 reject 或條件邏輯判斷錯誤）卻沒有對應地呼叫 continueRender()。

解決方法： 仔細檢查你的程式碼，確保每一條執行路徑都會呼叫 continueRender()。

import { delayRender, continueRender } from "remotion";
import { useState, useEffect } from "react";
 
export const MyComp = () => {
  const [handle] = useState(() => delayRender());
  const [data, setData] = useState(null);
 
  useEffect(() => {
    fetch("https://api.example.com/data")
      .then((res) => res.json())
      .then((json) => {
        setData(json);
        continueRender(handle); // ✅ 成功時呼叫
      })
      .catch((err) => {
        console.error(err);
        continueRender(handle); // ✅ 失敗時也要呼叫，否則會逾時
      });
  }, []);
 
  if (!data) return null;
  return <div>{data.title}</div>;
};

沒有網路連線或防火牆封鎖

如果你的元件依賴網路資源（字體、圖片、影片、音訊等），而在渲染環境中這些請求被防火牆封鎖或無法連線，Remotion 將永遠等不到資源載入完成。

雲端渲染環境尤其需要注意：例如 Amazon VPC 預設可能會封鎖對外的網路請求，導致逾時。

解決方法： 確認渲染環境中所有需要的網路資源都可以正常存取。

記憶體壓力

當並行渲染數量（concurrency）設定過高時，Chrome 可能無法順利載入所有的 <Html5Video> 元件，進而觸發逾時錯誤。

暫時解法： 降低 concurrency 設定，讓 Chrome 有足夠記憶體載入影片資源。

Remotion 版本過舊

早期版本（尤其是 1.x）在匯入大型資源時可能發生逾時問題。

解決方法： 升級到最新版本：

npm run upgrade

影片需要下載才能渲染

使用 <OffthreadVideo> 渲染時，影片必須先完整下載後才能讀取幀資料。若影片檔案很大，下載時間超過預設的逾時限制，就會觸發此錯誤。

解決方法： 增加逾時時間（見下方說明）。

增加逾時時間

此功能從 Remotion v2.6.3 起提供。

某些情況下，你無法避免某個幀需要超過 30 秒才能完成渲染，例如：

複雜的 WebGL 場景
昂貴的資料前處理
需要等待大型影片完整下載

你可以透過以下任一方式增加逾時限制：

1. 在 Remotion Studio 的渲染對話框中設定

開啟渲染對話框，在「進階」（Advanced）選項中調整逾時時間。

2. 使用 CLI 旗標

npx remotion render --timeout=60000

3. 在 Node.js API 中設定

renderStill()、renderFrames()、getCompositions()、renderMedia()、renderMediaOnLambda()、renderStillOnLambda()、renderMediaOnVercel()、renderStillOnVercel()、renderStillOnCloudRun() 以及 renderMediaOnCloudRun() 等函式都支援 timeoutInMilliseconds 選項：

import { renderMedia, selectComposition } from "@remotion/renderer";
 
await renderMedia({
  composition,
  serveUrl,
  codec: "h264",
  outputLocation: "out/video.mp4",
  timeoutInMilliseconds: 60000, // 設定為 60 秒
});

4. 在設定檔中設定

// remotion.config.ts
import { Config } from "@remotion/cli/config";
 
Config.setDelayRenderTimeoutInMilliseconds(60000);

5. 針對個別 delayRender() 呼叫設定

此功能從 Remotion v4.0.140 起提供。

import { delayRender } from "remotion";
 
const handle = delayRender("Fetching large dataset...", {
  timeoutInMilliseconds: 60000, // 僅針對此次等待延長至 60 秒
});

6. 針對媒體元件設定

<Img>、<Audio>、<Video>、<Html5Audio>、<Html5Video> 和 <IFrame> 等元件都支援 delayRenderTimeoutInMilliseconds 屬性（v4.0.140+）：

import { Img } from "remotion";
 
<Img
  src="https://example.com/large-image.jpg"
  delayRenderTimeoutInMilliseconds={60000}
/>

加入標籤協助除錯

此功能從 Remotion v2.6.13 起提供。

當你遇到逾時錯誤但不確定是哪個 delayRender() 呼叫造成的，可以在呼叫時加入描述性標籤：

delayRender("Fetching data from API...");

如果該呼叫逾時，錯誤訊息將會包含你的標籤：

Uncaught Error: A delayRender() "Fetching data from API..." was called but not cleared after 28000ms.
See https://remotion.dev/docs/timeout for help.
The delayRender was called

這讓你能夠快速鎖定是哪一段程式碼造成了逾時。

常見特定錯誤

`Loading <Img> with src http://localhost:3000/proxy`

如果你看到此類錯誤訊息，請參考相關的專項文件進行排查。

問題未解決？

如果以上方法都無法解決你的問題，請在 GitHub 上開一個 Issue，並提供可重現的範例。Remotion 團隊會盡力提供協助。