Lambda 疑難排解與除錯

本文說明如何針對 Remotion Lambda 渲染失敗進行系統化的疑難排解與除錯。

一般除錯策略

建議依照以下步驟進行排查：

透過 CLI 重現渲染：執行 npx remotion lambda render 指令，使用 --props 傳入與失敗渲染相同的輸入參數，並加上 --log=verbose 以取得詳細的除錯資訊。
等待渲染完全逾時或拋出錯誤：不要中途中斷，讓渲染自然結束或出現錯誤訊息。
仔細閱讀錯誤訊息：利用輸出的日誌連結查閱詳細資訊。

渲染失敗的四大原因

渲染失敗通常來自以下四種原因：

React 程式碼中發生錯誤
呼叫 delayRender() 後發生逾時
負責渲染某個 chunk 的 Lambda 函式逾時
主要 Lambda 函式逾時

React 程式碼錯誤

若你的程式碼拋出錯誤，可以在日誌中看到錯誤訊息。透過 CLI 進行渲染時，錯誤會經過符號化處理（symbolication），有助於定位程式碼中的錯誤位置。

修正錯誤後，重新部署網站並重新渲染即可。

逾時問題

判斷逾時類型

delayRender() 逾時：若錯誤訊息顯示 delayRender() 呼叫逾時，表示函式呼叫了 delayRender() 但未在逾時期間內呼叫 continueRender()，通常是程式碼中的 bug 所導致。

可透過 renderMediaOnLambda() 的 timeoutInMilliseconds 參數，或 CLI 的 --timeout 旗標來增加逾時時間。

主要 Lambda 函式逾時：若錯誤訊息顯示主要 Lambda 函式已逾時，表示渲染仍在進行中，但 Lambda 函式已達到最大執行時間上限。可能原因包含：

渲染花費時間超過指定時長，需透過部署函式時的 --timeout 旗標增加函式逾時時間
渲染存在瓶頸而緩慢，需測量並最佳化渲染效能
某個 chunk 卡住，導致主函式無法完成串接作業

查閱日誌

取得日誌 URL

使用 CLI：在指令中加入 --log=verbose，將會在終端機輸出 CloudWatch 連結
使用 renderMediaOnLambda()：加入 logLevel: "verbose" 選項，回傳值中會包含 cloudWatchLogs 欄位

開啟連結並在需要時登入 AWS，即可查看日誌串流。預設篩選條件為：

method=renderer,renderId=[render-id]

查找特定 chunk 的日誌

調整查詢條件以找到特定 chunk 的日誌，例如查找 chunk 12：

method=renderer,renderId=[render-id],chunk=12

在日誌串流中，可以看到 Remotion 的除錯記錄以及 React 程式碼中的 console.log 輸出。

查找主函式的日誌

method=launch,renderId=[render-id]

應會得到一筆結果，點擊藍色連結即可開啟日誌串流。

找出失敗的 Chunk

若要找出哪些 chunk 渲染失敗：

在 CLI 渲染時加入 --log=verbose，尋找指向 progress.json 的連結
若使用 renderMediaOnLambda()，回傳值中會有 folderInS3Console 欄位，可在其中找到 progress.json 檔案
在 progress.json 中，找到 chunks 陣列，其中缺少的項目即為渲染失敗的 chunk

找出缺少的 chunk 後，查閱該 chunk 的日誌以找到錯誤原因。

逾時時間的兩種類型

Remotion Lambda 中涉及兩種逾時設定，請勿混淆：

逾時類型	CLI 參數	API 參數
`delayRender()` 逾時	`npx remotion lambda render --timeout`	`renderMediaOnLambda()` 的 `timeoutInMilliseconds`
Lambda 函式逾時	`npx remotion lambda functions deploy --timeout`	`deployFunction()` 的 `timeoutInSeconds`

回報問題

若需要回報問題，可前往 GitHub 或 Discord 提交。

為了提供可重現的範例，請分享失敗渲染的 S3 資料夾中位於 renders/[render-id]/progress 路徑下的 progress.json 檔案。