疑難排解能力
快速分流流程
- 用一個目標重現（
--browser=chromium）。 - 移除自訂 profile 與 binary 旗標。
- 確認問題是否發生在
dev、build或兩者皆有。 - 一次修一類錯誤（重啟、相依、路徑或啟動）。
快速診斷決策樹
常見問題
需要重啟的診斷
如果你看到需要重啟的錯誤，請停止後重新執行extension dev。
典型觸發條件：
- Manifest entrypoint 清單變更。
- 在
pages/或scripts/中新增／移除檔案。 - 結構性的 HTML 腳本／樣式 entry 變更。
缺少可選相依
CLI 會按需安裝某些整合（例如 Vue／Preact 重整工具、樣式預處理器）。 如果 CLI 提示安裝可選相依：- 允許安裝。
- 重新啟動
extension dev。 - 相依安裝完成後再執行一次。
瀏覽器二進位問題
如果目標瀏覽器啟動失敗：- 確認自訂 binary 路徑（
--chromium-binary/--gecko-binary）。 - 確認瀏覽器目標與提供的 binary 相容。
- 退回到預設
chromium目標以隔離設定問題。
Build 能跑但 preview 顯示的是錯誤的程式碼
preview 會在 dist/<target> 存在時載入它，不存在時則退回到原始碼 manifest 所在的資料夾，因此缺少 build 輸出時它會執行未建置的原始碼，而不是直接失敗。
- 執行
extension build --browser=<target>。 - 再執行
extension preview --browser=<target>。
Manifest 引用錯誤
如果 build 回報缺少的 manifest 檔案：- 確認路徑是相對於 manifest 位置。
- 確認開頭
/的用法（public-root 語意）。 - 確認檔案實際上存在於原始碼／public 位置。
Docker、開發容器與 Codespaces
當在容器中執行時，開發伺服器預設綁定在127.0.0.1，因此主機無法連到。
- 加上
--host 0.0.0.0綁定到所有介面。 - 使用
--port 0讓 OS 在8080被占用時自動指派可用連接埠。 - 如果在持續整合（CI）容器中瀏覽器連線緩慢或不穩定，請透過 瀏覽器傳輸調校變數 增加連線逾時。
scripts/ 資料夾中的 Node.js 腳本
如果 build 失敗並顯示 scripts/ is a reserved folder in Extension.js，代表你在 scripts/ 特殊資料夾中放了 Node.js 檔案。Extension.js 會把 scripts/ 中的每個檔案以瀏覽器 content-script runtime 包起來，只能在 Node.js 執行的檔案會在這種情境下失敗。
把檔案移到專案根目錄下的其他資料夾（例如 bin/、tools/ 或 ci-scripts/）。詳情請見 特殊資料夾。
content_scripts/content-0.css 出現 net::ERR_FILE_NOT_FOUND
主控台出現一條紅色請求：chrome-extension://<id>/content_scripts/content-0.css，狀態是 net::ERR_FILE_NOT_FOUND，但擴充功能仍然正常運作。
在 Extension.js 4.1.10 之前，沒有樣式表的 content script 仍會請求一個同層的 content-0.css，而建置從未輸出這個檔案。這個請求無害，但會在主控台裡保持紅色。修正已隨 4.1.10 發佈，請升級：
- 執行
npx extension@latest dev使用最新的 CLI，或提升package.json中extension相依的版本。
css，那麼這個檔案是真實存在的，必須出現在 dist/<browser>/content_scripts/ 中。這種情況下檔案缺失是建置問題，而不是這個幻影請求。
擴充功能頁面的 URL 帶有 ?rspack-dev-server-hot=false 並整頁重新載入
在 extension dev 中，options、popup 或 sidebar 頁面的 URL 以 ?rspack-dev-server-hot=false&webpack-dev-server-hot=false 結尾。每次修改都會重新載入整個頁面，而不是原地更新。
從 3.18.1 到 4.1.9，Extension.js 會刻意加上這些參數。它們關閉了 HTML 頁面上的 hot module replacement，因此頁面會退回到整頁重新載入。4.1.10 版為這些頁面開啟了 hot module replacement，並從 URL 中移除舊參數。請升級：
- 執行
npx extension@latest dev使用最新的 CLI，或提升package.json中extension相依的版本。
修正後仍卡住
如果問題仍然存在：- 清掉暫時的假設，在乾淨的終端 session 重現。
- 縮減到仍會失敗的最小 manifest／entrypoint 案例。
- 記錄精確的指令與錯誤輸出以便回報問題。
除錯清單
- 先用單一瀏覽器目標重現（
--browser=chromium）。 - 在沒有自訂 profile／binary 旗標的情況下重現。
- 確認問題是否在
dev與build中都出現。 - 同時動到 manifest 與 entrypoint 檔案時，一次只改一個變更。