> ## Documentation Index > Fetch the complete documentation index at: https://extension.js.org/llms.txt > Use this file to discover all available pages before exploring further. # 错误码 > Extension.js schema-1 信封所使用的、长期稳定的 E_* 错误码表，按领域分组，并附上 codes.json 中的折叠名与历史名映射。 请基于稳定的错误码来做分支判断，绝不要基于消息文本。 每一个失败信封都会带上同一张表中的某个 `E_*` 错误码。错误码只会新增，绝不会被重命名或移除。错误码旁边的消息属于自由文案，任何一个版本都可能改动。 这张表随 `extension-develop/contract/codes.json` 一起发布，参见 [结果信封](/docs/contracts/result-envelope)。 ## 用法 | 错误码 | 含义 | | ---------------------------------- | -------------------------------------- | | `E_ARGS` | 缺少必填参数，或调用方式不合法。 | | `E_INVALID_OPTION` | 某个 flag 或参数的取值不在允许集合内。 | | `E_FLAG_VALUE_INVALID` | 某个 flag 的取值未通过校验。 | | `E_FLAG_NOT_SUPPORTED_HERE` | 该 flag 存在，但不适用于这个命令或这个目标。 | | `E_REMOVED_FLAG` | 该 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` 在加载时抛出了异常。 | | `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_MANIFEST_SHAPE` | 某个 manifest 字段的结构不正确。 | | `E_MANIFEST_PAGE_MISSING` | manifest 引用的某个 HTML 页面不存在。 | | `E_MANIFEST_VERSION_UNSUPPORTED` | 该目标不支持这个 `manifest_version`。 | | `E_MANIFEST_LOAD_BLOCKERS` | manifest 中存在浏览器在加载时会拒绝的字段。 | | `E_MANIFEST_PERMISSION_MISSING` | manifest 中缺少某个必需的权限。 | | `E_MANIFEST_MSG_KEY_MISSING` | 默认语言环境中缺少某个 `__MSG_x__` 键。 | | `E_MANIFEST_EMIT` | manifest 的产出或持久化失败。 | | `E_RESTART_REQUIRED` | 某个入口点字段发生了变化，开发服务器必须重启。 | ## 编译 | 错误码 | 含义 | | ---------------------------- | --------------------------------------- | | `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_REMOTE_FETCH_TIMEOUT` | 某次远程拉取超出了它的超时时间。 | | `E_REMOTE_DOWNLOAD` | 远程扩展的下载或解压失败。 | | `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` | 给定的二进制路径不存在，或不可执行。 | | `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` | 调试连接无法建立。 | | `E_BROWSER_CONNECTION_CLOSED` | 调试套接字在会话中途关闭。 | | `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_DEV_SERVER_TIMEOUT` | 开发服务器启动超出了它的超时时间。 | | `E_PORT_IN_USE` | 请求的端口已被占用，已自动改用其他端口。 | | `E_PORT_UNAVAILABLE` | 在请求端口附近找不到可绑定的空闲端口。 | ## 就绪契约 | 错误码 | 含义 | | ---------------------- | --------------------- | | `E_SESSION_NOT_FOUND` | 该项目与浏览器没有存活的会话契约。 | | `E_SESSION_EXISTS` | 该项目与浏览器已经存在一个存活会话。 | | `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_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_CREATE_DIR` | 无法创建目标目录。 | | `E_CREATE_WRITE` | 某个脚手架文件无法写入。 | | `E_CREATE_TESTS_SETUP` | 内置测试环境的初始化失败。 | | `E_GIT_SKIPPED` | 因为没有 git，所以跳过了 `git init`。 | ## 其他所有情况 | 错误码 | 领域 | 含义 | | ------------------------ | --------- | ---------------------- | | `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`）。 如果你的消费方遇到了表中没有的名称，请先通过这些映射把它解析出来，然后再做分支判断。 ## 下一步 * 在 [结果信封](/docs/contracts/result-envelope) 中了解错误码会流经哪些地方。 * 在 [生命周期流](/docs/contracts/lifecycle-stream) 中实时观察失败帧。