錯誤碼

請依穩定的錯誤碼做分支判斷，絕不要依訊息文字。每一個失敗信封都會帶上同一張表中的某個 E_* 錯誤碼。錯誤碼只會新增，絕不會被改名或移除。錯誤碼旁邊的訊息屬於自由文案，任何版本都可能更動。這張表隨 extension-develop/contract/codes.json 一起發布，參見結果信封。

用法

錯誤碼	意義
`E_ARGS`	缺少必要引數，或呼叫方式格式錯誤。
`E_INVALID_OPTION`	某個旗標或引數的值不在允許的集合內。
`E_FLAG_VALUE_INVALID`	某個旗標的值未通過驗證。
`E_FLAG_NOT_SUPPORTED_HERE`	該旗標存在，但不適用於這個指令或這個目標。
`E_REMOVED_FLAG`	該旗標已從 CLI 移除。
`E_UNKNOWN_COMMAND`	沒有子指令符合這個名稱。
`E_NODE_VERSION`	執行中的 Node 版本低於支援的最低版本。
`E_COMMAND_UNSUPPORTED_FOR_TARGET`	該指令不支援所要求的瀏覽器目標。
`E_UNSUPPORTED_BROWSER`	所要求的廠商不在支援的瀏覽器清單內。
`E_BROWSER_NOT_INSTALLABLE`	該瀏覽器隨作業系統提供，CLI 無法安裝它。
`E_PARENT_GONE`	`--parent-pid` 指定的宿主處理程序已死亡，開發伺服器因而自行結束。
`E_REMOTE_URL_UNSUPPORTED`	該操作不接受遠端 URL。

專案

錯誤碼	意義
`E_PROJECT_NOT_FOUND`	解析出的專案資料夾不存在。
`E_CONFIG_LOAD`	`extension.config.js` 在載入時拋出例外，或匯出的不是物件。`dev`、`build`、`start` 與 `preview` 都以此代碼回應。
`E_MANAGED_DEP_CONFLICT`	專案宣告了一個由工具鏈託管的套件。
`E_DEPENDENCY_INSTALL`	安裝專案相依套件失敗。
`E_TYPES_EMIT`	寫出 `extension-env.d.ts` 失敗。
`E_TSCONFIG_MISSING`	存在 TypeScript 原始碼，但 `package.json` 旁沒有 `tsconfig.json`。
`E_OPTIONAL_DEP_UNRESOLVED`	某個選用相依契約無法解析。
`E_OPTIONAL_DEP_LOAD`	某個選用相依已解析，但載入失敗。
`E_OPTIONAL_DEP_UNKNOWN`	未知的選用相依契約 id。
`E_COMPANION_EXTENSION_PATH`	某個搭配擴充功能路徑逸出了 `extensions/`，或未產出任何未封裝內容。
`E_MANIFEST_IN_PUBLIC`	`manifest.json` 被放在 `public/` 底下。
`E_RUNTIME_NOT_FOUND`	extension-develop 執行階段遺失或未編譯。

Manifest

錯誤碼	意義
`E_MANIFEST_NOT_FOUND`	解析出的根目錄下沒有 `manifest.json`。
`E_MANIFEST_INVALID`	manifest 不是可解析的 JSON，或不是 WebExtension manifest。

編譯

錯誤碼	意義
`E_FIRST_COMPILE`	工作階段的第一次編譯失敗，因此什麼都沒有載入。
`E_COMPILE`	編譯結束時帶有錯誤。
`E_COMPILE_FATAL`	編譯器本身失敗，或回傳了無法使用的統計資料。
`E_MODULE_NOT_FOUND`	某個模組識別字無法解析。
`E_ENTRY_NOT_FOUND`	某個 manifest、HTML 或 JSON 進入點指向不存在的檔案。
`E_ASSET_MISSING`	缺少某個圖示、靜態資源或 JSON 相依。
`E_SCRIPT_DEP_MISSING`	某個執行階段指令稿相依無法被追蹤到。
`E_RESERVED_FOLDER`	違反了保留的 `scripts/` 資料夾結構。
`E_CSS_PARSE`	某個樣式表解析失敗。
`E_CSS_PREPROCESSOR_MISSING`	要求了某個 CSS 前處理器，但無法解析到它。
`E_CSS_DEAD_REF`	CSS 中的某個 `url()` 指向不存在的內容。
`E_INTEGRATION_INSTALL`	某個框架整合安裝失敗。
`E_POLYFILL_NOT_FOUND`	要求了 webextension-polyfill，但它並不存在。
`E_LOCALES_LAYOUT`	`_locales` 的結構或 `messages.json` 不合法。
`E_WAR_INVALID`	`web_accessible_resources` 的結構或比對樣式遭到拒絕。
`E_MATCH_PATTERN_INVALID`	瀏覽器拒絕了某個 content script 的比對樣式。
`E_BACKGROUND_REQUIRED`	重新載入執行階段需要一個 background chunk，但它並不存在。
`E_CONTENT_SCRIPT_SYNTAX`	某個 content script 解析失敗。
`E_NO_ENTRYPOINTS`	這次編譯產出了零個進入點。
`E_REMOTE_RESOURCE_BLOCKED`	某個遠端指令稿或樣式表被擴充功能 CSP 封鎖。
`E_PERF_BUDGET`	某個資源超出了它的大小預算。
`E_ZIP_SKIPPED`	打包因某個已說明的原因被略過。
`E_ENV_NO_MATCH`	沒有任何 `.env` 檔案符合目前模式。

E_COMPILE 和 E_FIRST_COMPILE 是編譯失敗時的頂層錯誤碼。上表中有十五列會出現在該影格的 error.details 裡，每條診斷一個：E_MODULE_NOT_FOUND、E_CONTENT_SCRIPT_SYNTAX、E_CSS_PARSE、E_ENTRY_NOT_FOUND、E_ASSET_MISSING、E_SCRIPT_DEP_MISSING、E_RESERVED_FOLDER、E_CSS_PREPROCESSOR_MISSING、E_CSS_DEAD_REF、E_LOCALES_LAYOUT、E_WAR_INVALID、E_BACKGROUND_REQUIRED、E_REMOTE_RESOURCE_BLOCKED、E_PERF_BUDGET 和 E_ENV_NO_MATCH。同樣這些錯誤碼也會以 E_CODE: 前綴出現在成功建置的 warnings 字串開頭。見編譯診斷。

遠端專案與網路

錯誤碼	意義
`E_REMOTE_FETCH_TIMEOUT`	某次遠端擷取超過了它的逾時時間。
`E_REMOTE_DOWNLOAD`	遠端擴充功能無法下載或無法寫入磁碟，例如連線遭拒或 HTTP 錯誤。訊息為 `Couldn't download the ZIP file or write it to disk.`
`E_REMOTE_ZIP_INVALID`	該遠端 URL 回傳的並不是 ZIP、回傳的封存檔已損毀無法解開，或回傳的封存檔含有位於其資料夾之外的條目。最後這種封存檔會在寫入任何內容之前遭拒，訊息會點名該條目，也不會建議重試。
`E_LOCAL_ZIP_NOT_FOUND`	被參照的本機 zip 遺失，或根本不是 zip。
`E_PROJECT_DOWNLOAD_EMPTY`	下載成功，但解壓出的資料夾並不存在。
`E_NETWORK`	某個網路請求失敗或逾時。

瀏覽器執行檔與啟動

錯誤碼	意義
`E_BROWSER_NOT_FOUND`	所要求的廠商沒有已安裝的執行檔。
`E_BROWSER_BINARY_REQUIRED`	`-based` 目標需要明確的執行檔路徑。
`E_BROWSER_BINARY_INVALID`	固定的 `--chromium-binary` 或 `--gecko-binary` 不存在、不是可執行檔，或在 10 秒內沒有回應版本探測。從 4.1.39 之後的版本起，`FIREFOX_BINARY` 這類執行檔變數指向不存在或不可執行的路徑時，也以同樣的方式失敗。`start`、`dev` 與 `preview` 都以狀態 `usage` 回應它。
`E_BROWSER_LAUNCH`	瀏覽器處理程序無法產生，或在啟動時就死掉了。
`E_BROWSER_EXITED`	已啟動的瀏覽器結束了，而伺服器仍在執行。
`E_BROWSER_START_TIMEOUT`	瀏覽器始終沒有送出啟動訊號。
`E_PROFILE_LOCKED`	該設定檔目錄被另一個瀏覽器處理程序占用。
`E_LAUNCH_SKIPPED_COMPILE_ERRORS`	因為編譯失敗，所以沒有啟動瀏覽器。
`E_INSTANCE_AMBIGUOUS`	有多個存活的實例符合所要求的 id。
`E_WSL_INTEROP`	WSL 互通無法解析到 Windows 上的瀏覽器。
`E_BROWSER_DOWNLOAD`	下載或安裝瀏覽器失敗。
`E_BROWSER_INSTALL_PRIVILEGE`	這次安裝需要一個互動式的特權工作階段。
`E_BROWSER_UNINSTALL`	移除已安裝的瀏覽器失敗。
`E_UNINSTALL_NOOP`	沒有可以移除的東西。

瀏覽器執行階段

錯誤碼	意義
`E_EXTENSION_LOAD_REFUSED`	瀏覽器拒絕了這個未封裝的擴充功能。
`E_ADDON_INSTALL`	Gecko 暫時附加元件安裝失敗。

除錯協定

錯誤碼	意義
`E_BROWSER_CONNECT`	無法開啟除錯連線，例如 Firefox 的除錯器始終沒有回應。
`E_BROWSER_CONNECTION_CLOSED`	除錯 socket 在工作階段中途關閉。
`E_CDP_NOT_CONNECTED`	在沒有存活 CDP 傳輸的情況下發出了某個操作。
`E_CDP_TIMEOUT`	某個 CDP 指令或 load 事件逾時。
`E_CDP_OP_FAILED`	透過 CDP 執行的某個擴充功能操作失敗。
`E_EXTENSION_ID_UNKNOWN`	無法透過 CDP 判定擴充功能 id。
`E_RDP_PROTOCOL`	出現格式錯誤或非預期的 RDP 交換。

開發伺服器

錯誤碼	意義
`E_DEV_SERVER_START`	開發伺服器啟動失敗。
`E_PORT_IN_USE`	所要求的埠號已被占用，已自動改用其他埠號。
`E_PORT_UNAVAILABLE`	在所要求的埠號附近找不到可綁定的空閒埠號。

就緒契約

錯誤碼	意義
`E_SESSION_NOT_FOUND`	這個專案與瀏覽器沒有存活的工作階段契約。
`E_SESSION_STOPPED`	工作階段契約回報該工作階段已停止。
`E_READY_TIMEOUT`	工作階段尚未就緒，`--wait` 就已逾時。
`E_READY_ERROR_STATUS`	就緒契約回報該工作階段處於錯誤狀態。

控制通道

錯誤碼	意義
`E_CONTROL_UNAVAILABLE`	控制通道不存在、不相符，或沒有回應。
`E_CONTROL_DENIED`	工作階段拒絕了這次控制操作。
`E_TOKEN_MISSING`	該操作需要一個工作階段權杖，但它並不存在。
`E_EVAL_REFUSED`	該工作階段停用了 eval，或權杖不相符。
`E_TIMEOUT`	該操作在逾時時間內沒有回應。
`E_NOT_IMPLEMENTED`	該操作在這個情境或這個引擎上尚未實作。
`E_TARGET_NOT_FOUND`	沒有任何分頁、frame 或情境符合所要求的目標。
`E_HEADED_WINDOW_REQUIRED`	該介面需要一個有頭的瀏覽器視窗，而這個工作階段沒有。
`E_USER_GESTURE_REQUIRED`	該介面需要一次真實的使用者手勢，而呼叫端無法合成它。
`E_EVAL`	被求值的運算式在頁面內拋出例外。
`E_CSP_BLOCKS_EVAL`	目標的內容安全政策禁止 eval，因此任何運算式都無法在那裡執行。
`E_INSPECT`	在受檢端內部進行 DOM 檢查失敗。
`E_STORAGE`	`chrome.storage` 拒絕了這次讀取或寫入。

日誌

錯誤碼	意義
`E_LOGS_NOT_FOUND`	這個專案與瀏覽器沒有日誌串流。
`E_LOGS_STREAM_GAP`	follow 串流掉了部分事件。

建立

錯誤碼	意義
`E_TEMPLATE_NOT_FOUND`	該範本不在目錄清單中，或沒有 manifest。
`E_DESTINATION_NOT_EMPTY`	目的地已經有會衝突的檔案。
`E_DESTINATION_NOT_WRITABLE`	目的地目錄無法寫入。

其他所有情況

錯誤碼	領域	意義
`E_PREVIEW_NO_DIST`	preview	解析出的輸出路徑下沒有未封裝的擴充功能。
`E_SAFARI_TOOLCHAIN`	safari	Safari 工具鏈不可用，或某次呼叫失敗。
`E_PUBLISH_REJECTED`	publish	平台拒絕了這次上傳。
`E_AUTH_REQUIRED`	publish	該操作需要一個驗證權杖，但它並不存在。
`E_TELEMETRY_WRITE`	telemetry	無法寫入遙測同意檔案。
`E_DOCTOR_CHECKS_FAILED`	doctor	有一項或多項 doctor 檢查回報失敗。
`E_INTERRUPTED`	internal	該操作在完成之前被中斷。
`E_INTERNAL`	internal	一個非預期的錯誤傳到了最上層的錯誤匯集點。

折疊名稱與舊名稱

codes.json 在這張表之外還帶了兩份額外對應：

folded 把較細的清單名稱對應到已發布的家族錯誤碼上。例如 E_ARG_REQUIRED 會折疊為 E_ARGS，E_BROWSER_NOT_INSTALLED 會折疊為 E_BROWSER_NOT_FOUND。
legacy 把信封出現之前的三種命名慣例對應到這張表上：ready.json 的 snake_case 錯誤碼（profile_locked 對應 E_PROFILE_LOCKED）、PascalCase 的錯誤名稱（TargetNotFound 對應 E_TARGET_NOT_FOUND），以及 kebab-case 的 doctor 檢查項 id（eval-token 對應 E_TOKEN_MISSING）。

如果你的取用端遇到表中沒有的名稱，請先透過這些對應解析出來，再做分支判斷。

下一步

在結果信封中了解錯誤碼會流經哪些地方。
在生命週期串流中即時觀察失敗訊框。

Introduction

Browser extension fundamentals

Getting started

範本

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

用法

專案