升級 Remotion

Remotion 會定期發布新版本，帶來效能改善、新功能和 Bug 修復。本文說明如何安全地升級你的 Remotion 專案。

升級指令

Remotion 提供官方的升級工具，可以一次更新所有相關套件：

npx remotion upgrade

這個指令會自動偵測你專案中所有 @remotion/* 套件，並將它們升級到最新的相容版本。

如果你想升級到特定版本：

npx remotion upgrade 4.0.0

手動升級

若要手動升級，需要同時更新 remotion 以及你所使用的所有 @remotion/* 子套件，確保版本一致：

npm install remotion@latest @remotion/player@latest @remotion/cli@latest

重要：所有 remotion 相關套件的版本號必須完全一致，版本不符會導致執行時期錯誤。你可以在版本不符問題排除頁面找到更多資訊。

查看變更記錄

升級前，建議先查看官方 Changelog：

GitHub Releases：github.com/remotion-dev/remotion/releases
官方文件：remotion.dev/docs/changelog

主要版本的重大變更

Remotion 4.x

Remotion 4 是目前的主要版本，帶來以下重大改進：

<OffthreadVideo> 成為推薦的影片元件，取代 <Video> 作為渲染首選
Lambda 渲染 架構更新，支援更大規模的批次渲染
Props 結構 透過 Zod Schema 驗證，提升型別安全性
@remotion/transitions 正式推出，提供內建轉場效果套件
Studio 介面全面翻新，支援視覺化編輯屬性

從 3.x 遷移到 4.x 的主要調整

// 舊：3.x 的 Video 元件
import { Video } from "remotion";
<Video src={videoSrc} />
 
// 新：4.x 建議使用 OffthreadVideo（渲染更可靠）
import { OffthreadVideo } from "remotion";
<OffthreadVideo src={videoSrc} />

// 舊：3.x 的 Props 定義
registerRoot(RemotionRoot);
 
// 新：4.x 支援 Zod Schema 驗證
import { z } from "zod";
 
const mySchema = z.object({
  title: z.string(),
  color: z.string(),
});
 
<Composition
  id="MyVideo"
  component={MyComponent}
  schema={mySchema}
  defaultProps={{ title: "Hello", color: "#fff" }}
  // ...
/>

Remotion 3.x

引入 @remotion/lambda 雲端渲染支援
新增 @remotion/player 網頁播放器元件
delayRender / continueRender API 趨於穩定

升級後的驗證步驟

執行 Studio，確認所有 Composition 可以正常預覽：
```
npm start
```

試渲染一個短片段，確認渲染流程無誤：

npx remotion render MyComposition out/test.mp4 --frames=0-30

執行測試套件（若有）：
```
npm test
```
檢查 Lambda 設定（若使用雲端渲染），確認 Lambda 函式版本與本地 SDK 一致：
```
npx remotion lambda functions ls
```

固定版本（不自動升級）

若專案對穩定性要求極高，可在 package.json 中固定精確版本，避免意外升級：

{
  "dependencies": {
    "remotion": "4.0.100",
    "@remotion/cli": "4.0.100",
    "@remotion/player": "4.0.100"
  }
}

移除版本前的 ^ 符號，即可鎖定版本。

常見升級問題

升級後出現「版本不符」錯誤？ 確認所有 remotion 相關套件版本完全一致。執行 npm ls remotion 查看實際安裝的版本。

Lambda 渲染在升級後失敗？ Lambda 的部署版本需與本地 SDK 版本匹配。重新部署 Lambda 函式：

npx remotion lambda functions deploy

某個 API 在升級後消失或改名？ 查閱對應版本的官方 Changelog，通常會有棄用警告和遷移說明。