Remotion 最佳實踐
將 Remotion 輸出建構成幀、輸入屬性與宣告資產的決定性函數。除非任務需要變更，否則保留使用者編輯與專案現有的套件管理工具、架構與風格。
從證據開始
- 閱讀儲存庫指示，並檢查
package.json、鎖定檔、Remotion 設定檔、進入點、已註冊的合成，以及鄰近的測試。 - 在現有專案上，執行
node <skill-directory>/scripts/audit-remotion-project.mjs <project-root>。將其輸出視為證據，而非升級的許可。 - 在選擇 API 前記錄已安裝的 Remotion 版本。保持所有
remotion與@remotion/*套件在同一精確版本。不要新增第二個鎖定檔。 - 確定交付項目是影片、單張靜態畫面、從影片取樣的幀，還是一批商店截圖。
- 在實作前定義合成 ID、尺寸、FPS、持續時間、屬性、輸出路徑與所需資產。
僅載入相關參考
- 若使用
<Composition>、<Still>、useCurrentFrame()、interpolate()、spring()、<Sequence>或<Series>，請閱讀 composition-and-timing.md。 - 若使用
staticFile()、媒體、字型、網路資料、useDelayRender()、delayRender()或calculateMetadata()，請閱讀 assets-and-async.md。 - 若使用 CLI、
renderStill()、伺服器端渲染或 Remotion Lambda，請閱讀 rendering-and-lambda.md。 - 若遇到渲染緩慢、記憶體使用過高、非決定性行為或驗證策略問題，請閱讀 performance-and-testing.md。
- 若處理 App Store 或 Google Play 圖片（包括由
screenshot-studio委派的 1284×2778 輸出），請閱讀 store-stills.md。 - 當某個 API 或平台規則可能已變更時，請在撰寫程式碼前查閱 sources.md 中連結的即時主要來源。
不可妥協的實作規則
- 使用
useCurrentFrame()與useVideoConfig()推導時間。不要使用 CSS 轉場、CSS 關鍵影格動畫、牆鐘計時器或未設定種子的隨機性來產生動態效果。 - 除非故意外推，否則將有限動畫限制在邊界內。當時間表示時間長度時，以秒乘以
fps來表達時間，並集中管理共享場景的持續時間。 - 記住
useCurrentFrame()在計時元件內部是相對的。只有當需要全域同步時，才從合成根傳遞絕對幀。 - 使用
<Sequence>在父時間軸上明確放置，使用<Series>處理連續場景。為每個場景指定明確的持續時間。 - 將本地資產放在
public/中，並使用staticFile()解析。使用 Remotion 媒體元件而非原始 HTML 標籤，以便渲染正確等待媒體載入完畢。 - 偏好使用元件內部的
useDelayRender()。建立一次 handle，精確清除一次，並在失敗時呼叫cancelRender(error)。對於需要確定 props 或中繼資料的資料，偏好使用calculateMetadata()一次渲染。 - 保持渲染時的程式碼不包含僅在瀏覽器中可用的假設，這些假設在無頭 Chromium 或 Lambda 中無法使用。絕不將 AWS 憑證或其他機密暴露給瀏覽器 bundle。
- 為每個商店目標獨立驗證尺寸、檔案格式、Alpha 通道政策與平台特定規則。切勿假設一個直向尺寸同時適用於 Apple 與 Google。
在緊湊的渲染迴圈中工作
- 執行型別檢查與焦點測試。
- 渲染具代表性的靜態幀：起始幀、每個場景邊界、動態中途點與最後一幀。
- 檢查實際像素，而非僅依賴 Studio 預覽。檢查裁剪、文字換行、安全邊距、遺失資產與透明背景。
- 在進行完整的昂貴影片渲染前，先渲染一小段幀範圍或低解析度草稿。
- 根據部署機器進行並發基準測試，而非盲目最大化並發數。
- 使用明確的合成 ID、屬性、輸出路徑、尺寸與格式渲染最終成品。
- 驗證結束狀態、檔案是否存在、像素尺寸、持續時間/幀數（如相關）以及最終的視覺樣本。
保守地進行變更
- 除非任務要求或使用者同意，否則不要升級 Remotion、改寫專案結構或更換媒體元件。
- 將較新的 API 限制在已安裝的版本內；在可行時提供相容的降級方案。
- 不要透過任意增加逾時來隱藏渲染失敗。應先找出未解析的 handle、網路請求、資產、字型或媒體解碼問題。
- 未經可比渲染的測量結果，不要聲稱效能提升。