版本不匹配錯誤

問題說明

您安裝的所有 Remotion 相關套件（remotion、@remotion/player、@remotion/cli、@remotion/lambda 等）必須使用完全相同的版本號。

如果版本不一致，這些套件可能無法正確地互相通訊，導致難以察覺的細微錯誤，甚至完全無法運作。

^ 符號可能引起混淆

以下 package.json 無法確保所有 Remotion 套件版本相同：

{
  "dependencies": {
    "remotion": "^2.6.12",
    "@remotion/player": "^2.6.12",
    "@remotion/gif": "^2.6.12"
  }
}

^ 符號允許 npm 安裝符合語義版本（semver）規則的更新版本。如果套件是在不同時間分別安裝的，每個套件可能被更新到不同的版本。

以下寫法才能確保所有套件版本一致：

{
  "dependencies": {
    "remotion": "2.6.12",
    "@remotion/player": "2.6.12",
    "@remotion/gif": "2.6.12"
  }
}

建議做法：移除 ^ 符號，固定所有 Remotion 套件的版本號。

分批安裝的問題

當您在不同時間點分別安裝不同的 Remotion 套件時，特別容易出現版本不匹配：

# 第一次安裝（例如三個月前）
npm install remotion@2.6.12
 
# 後來新增其他套件時（此時最新版本已是 2.7.0）
npm install @remotion/player
# @remotion/player 被安裝為 2.7.0，與 remotion 2.6.12 不匹配！

解決方法： 升級所有 Remotion 套件時，務必同時更新，或使用固定版本號。

一次更新所有 Remotion 套件

使用官方提供的升級指令，可以同時更新所有 Remotion 套件至最新版本：

npx remotion upgrade

發布依賴 Remotion 的函式庫

如果您要將一個使用 Remotion 的函式庫發布到 npm，應將 Remotion 設定為 peerDependency 和 devDependency，而不是 dependency：

{
  "name": "my-remotion-library",
  "peerDependencies": {
    "remotion": "*"
  },
  "devDependencies": {
    "remotion": "^2.6.11"
  }
}

這樣做的好處是，當使用者將 my-remotion-library 安裝到他們的 Remotion 專案時，不會引入重複的 Remotion 套件：

{
  "dependencies": {
    // 不會發生版本不匹配，因為 `remotion` 不是
    // `my-remotion-library` 的直接相依套件
    "remotion": "2.7.0",
    "my-remotion-library": "1.0.0"
  }
}

確認已安裝的版本

package.json 中寫的是 ^2.6.11 並不代表實際安裝的就是 2.6.11。使用以下指令查看專案中實際安裝的所有 Remotion 套件及其版本：

npx remotion versions

輸出範例：

remotion                 4.0.1
@remotion/cli            4.0.1
@remotion/player         4.0.1
@remotion/lambda         4.0.0  ← 版本不匹配！

如果看到版本不一致，應立即修復。

快速修復步驟

1. 執行 npx remotion versions 確認哪些套件版本不匹配
2. 更新 package.json，將所有 Remotion 套件版本設為相同的固定版本號（移除 ^）
3. 刪除 node_modules 和 package-lock.json（或 yarn.lock）
4. 重新執行 npm install
5. 再次執行 npx remotion versions 確認所有版本一致

參見

• 升級 Remotion
• 套件相依管理