Fast Refresh 無法運作

問題說明

當你在 Remotion Studio 中修改程式碼後，預覽畫面沒有自動更新，就是 Fast Refresh 無法正常運作的症狀。

常見原因

原因一：Studio 伺服器已斷線

這是最常見的原因。當你使用 Ctrl+C 中斷或關閉了執行 npx remotion studio 的終端機視窗，Studio 的開發伺服器就會停止運行。

症狀：

• 瀏覽器中的 Remotion Studio 頁面無法重新整理
• 終端機沒有顯示任何重新編譯的訊息
• 瀏覽器主控台顯示 WebSocket 連線錯誤

解決方式：

重新啟動 Remotion Studio：

npx remotion studio

或者，若你使用套件管理器的腳本：

# npm
npm run dev
 
# yarn
yarn dev
 
# pnpm
pnpm dev

確認終端機中看到類似以下的訊息，代表伺服器正在運行：

Remotion Studio is ready.
Open http://localhost:3000 to get started.

原因二：檔案名稱的大小寫不一致

這是 Webpack 的一個已知問題。如果你的檔案名稱的實際大小寫與import 語句中的大小寫不一致，Fast Refresh 可能會失效。

錯誤範例：

假設你的實際檔案名稱是 MyComp.tsx，但你的 import 語句寫成：

// 錯誤：大小寫不一致
import { MyComp } from "./myComp"; // 實際檔案是 MyComp.tsx
import { MyComp } from "./mycomp"; // 實際檔案是 MyComp.tsx

在 macOS 和 Windows 上，檔案系統預設不區分大小寫，所以這樣的 import 可以成功解析，但 Webpack 的 Fast Refresh 模組追蹤邏輯可能會因此混淆，導致更新失效。

解決方式：

確保所有 import 語句中的路徑大小寫與實際檔案名稱完全一致：

// 正確：大小寫完全一致
import { MyComp } from "./MyComp"; // 實際檔案是 MyComp.tsx

檢查步驟：

1. 找到報告 Fast Refresh 失效的檔案
2. 查看該檔案被 import 的所有地方
3. 比對 import 路徑與實際檔案名稱的大小寫
4. 修正所有不一致的 import 語句

其他可能原因

語法錯誤

如果你的程式碼有語法錯誤，Webpack 可能無法完成重新編譯，導致更新失效。

解決方式： 查看終端機和瀏覽器主控台，確認沒有編譯錯誤。

循環依賴

若組件之間存在循環 import（A 引入 B，B 又引入 A），可能導致 Fast Refresh 失效。

解決方式： 使用工具（如 madge）檢測並消除循環依賴。

npx madge --circular src/

Node.js 版本問題

某些較舊的 Node.js 版本可能與 Remotion 的開發伺服器不相容。

解決方式： 確保使用 Remotion 要求的 Node.js 版本（建議 Node.js 18 或更高版本）。

診斷流程

Fast Refresh 沒有更新
      │
      ├─ 終端機還在執行嗎？
      │   ├─ 否 → 重新執行 npx remotion studio
      │   └─ 是 → 繼續往下
      │
      ├─ 終端機有顯示重新編譯訊息嗎？
      │   ├─ 否，有錯誤 → 修正語法或 import 錯誤
      │   └─ 是，有編譯成功 → 繼續往下
      │
      └─ 檢查 import 路徑的大小寫是否與檔案名稱一致
          └─ 不一致 → 修正大小寫

注意事項

大小寫不一致導致 Fast Refresh 失效是 Webpack 的已知錯誤（bug），Remotion 團隊已向 Webpack 提交問題回報，但修復需等待 Webpack 上游處理。

在問題修復前，保持 import 路徑與檔案名稱大小寫完全一致是最可靠的預防方式。

延伸閱讀

• Remotion Studio 文件
• 逾時問題排解