無法解析來源

錯誤訊息

Error: Source could not be parsed.

或類似的變體：

Source file could not be read or parsed.

Could not parse the entry point.

錯誤發生的時機

此錯誤通常在以下情況發生：

執行 bundle() 打包 Remotion 專案時
執行 npx remotion render 或 npx remotion studio 時
在 CI/CD 流程中啟動 Remotion 渲染工作時

常見原因與解決方案

原因一：進入點檔案路徑錯誤

最常見的原因是傳入 bundle() 或 CLI 的進入點路徑不正確。

CLI 使用範例：

# 確認路徑確實存在
npx remotion render src/remotion/index.ts MyComposition out/video.mp4

Node.js API 使用範例：

import { bundle } from '@remotion/bundler';
import path from 'path';
 
// 使用絕對路徑，避免相對路徑的歧義
const bundled = await bundle({
  entryPoint: path.resolve('./src/remotion/index.ts'),
});

請確認：

路徑的大小寫正確（Linux 和 macOS 的檔案系統區分大小寫）
副檔名正確（.ts、.tsx 或 .js）
從專案根目錄執行指令（而非從其他子目錄）

原因二：進入點缺少 `registerRoot()`

Remotion 的進入點檔案必須呼叫 registerRoot()，否則無法解析。

// src/remotion/index.ts — 正確的進入點
import { registerRoot } from 'remotion';
import { MyVideo } from './Root';
 
registerRoot(MyVideo);

若進入點沒有呼叫 registerRoot()，或匯入了錯誤的 Root 元件，都可能導致此錯誤。

原因三：語法錯誤

進入點或其相依檔案中存在 JavaScript / TypeScript 語法錯誤，導致 Webpack 無法解析。

先在編輯器或用 TypeScript 編譯器獨立檢查是否有語法問題：

# 使用 tsc 檢查型別錯誤
npx tsc --noEmit
 
# 若使用 ESLint，也可一併檢查
npx eslint src/remotion/

原因四：不支援的模組格式

Remotion 的 Webpack 設定預設支援 ESM（import/export）和 CommonJS（require/module.exports）。若你的進入點或依賴使用了不常見的模組格式，可能需要額外的 Webpack 設定。

檢查是否有任何套件使用了特殊格式：

# 查看 Webpack 的詳細錯誤輸出
npx remotion bundle src/remotion/index.ts --log=verbose

原因五：循環依賴（Circular Imports）

若專案中存在循環依賴（A 匯入 B，B 又匯入 A），可能導致解析失敗。使用工具偵測循環依賴：

npx madge --circular src/remotion/index.ts

解決方式是將共用的型別或工具函式提取至獨立模組，打破循環。

原因六：Node.js 原生模組

進入點的依賴鏈中若包含只能在 Node.js 中執行的原生模組（如 fs、path、child_process），Webpack 在打包時會無法解析這些模組。

Remotion 元件在瀏覽器環境中執行，不能直接使用 Node.js 內建模組。若確實需要，應在伺服器端邏輯中處理，再透過 inputProps 或資料預取的方式傳入元件。

進一步除錯

若以上方案都無法解決，可以嘗試：

查看完整的錯誤堆疊：加上 --log=verbose 參數取得更多資訊

npx remotion bundle src/remotion/index.ts --log=verbose

逐步簡化進入點：暫時移除部分匯入，找出造成問題的來源
確認 Node.js 版本：Remotion 要求 Node.js 16 以上版本

node --version

重新安裝依賴：

rm -rf node_modules package-lock.json
npm install