除錯失敗的渲染

當 Remotion 渲染失敗時，診斷問題的根本原因往往需要系統性的方法。本文介紹幾個有效的除錯步驟，幫助您快速定位並解決渲染問題。

1. 啟用詳細日誌

第一步是取得盡可能多的診斷資訊。

從 CLI 使用

在渲染指令中加入 --log=verbose 旗標：

npx remotion render MyComp out.mp4 --log=verbose

從 Node.js API 使用

在呼叫 renderMedia() 時加入 verbose: true 選項：

await renderMedia({
  composition,
  serveUrl,
  codec: "h264",
  outputLocation: "out.mp4",
  verbose: true,
});

注意： 如果您看到某個日誌出現多次，這是因為渲染工作被分配到多個執行緒執行。可以暫時設定 --concurrency=1，讓每條日誌只出現一次，方便閱讀。

2. 在專案中添加日誌

在您的元件程式碼中使用 console.log() 來了解執行順序，並驗證您對程式碼行為的假設。

import { useCurrentFrame } from "remotion";
 
export const MyComp = () => {
  const frame = useCurrentFrame();
  console.log("目前幀：", frame);
 
  return <div>幀 {frame}</div>;
};

這可以幫助您：

• 確認元件是否被呼叫
• 追蹤非預期的狀態值
• 找出在哪個幀發生錯誤

3. 逐一移除元件

採用二分法排除問題：逐一移除元件，直到影片為空白。在哪個步驟錯誤消失，就能確定是哪個元件導致了渲染失敗。

建議的排除流程：

1. 先將最複雜的元件替換成空的 <div>
2. 確認錯誤是否消失
3. 如果消失，問題在被移除的那個元件中
4. 如果未消失，繼續移除下一個元件
5. 重複直到找到問題根源

4. 搜尋已知問題與文件

在您深入除錯之前，建議先查看是否有人已經遇到相同的問題：

• 前往 Remotion GitHub Issues 搜尋相關問題
• 查閱官方文件——內容超過 300 頁，涵蓋許多常見問題的疑難排解指南
• 搜尋錯誤訊息的關鍵字

如果找到符合您情況的 Issue，可以在底下留言，幫助社群一起解決這個問題。

5. 尋求協助

如果以上步驟都無法解決問題，您可以透過以下管道尋求協助：

• GitHub Issues：在 Remotion 儲存庫提交詳細的錯誤報告
• Discord：加入 Remotion 社群，與其他開發者即時討論

提問時請提供：

• 錯誤訊息的完整內容
• 使用的 Remotion 版本
• 作業系統與 Node.js 版本
• 可重現問題的最小程式碼範例

Lambda 渲染的除錯

如果您是在 Remotion Lambda 上進行渲染，有專門的除錯指南可供參考。Lambda 渲染失敗可能有額外的原因，例如 IAM 權限不足、記憶體限制超出或函式逾時等。

參見

• 除錯 Lambda 渲染失敗
• 渲染逾時問題
• 尋求協助