E_* 错误码。错误码只会新增，绝不会被重命名或移除。错误码旁边的消息属于自由文案，任何一个版本都可能改动。
这张表随 extension-develop/contract/codes.json 一起发布，参见 结果信封。
用法
| 错误码 | 含义 |
|---|---|
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）。