错误码

请基于稳定的错误码来做分支判断，绝不要基于消息文本。每一个失败信封都会带上同一张表中的某个 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` 在加载时抛出了异常，或导出的不是一个对象。`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 秒内没有应答版本探测。`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`	调试套接字在会话中途关闭。
`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

用法

项目

Manifest

编译

远程项目与网络

浏览器二进制与启动

浏览器运行时

调试协议

开发服务器

就绪契约

控制通道

日志

创建

其他所有情况

折叠名与历史名

下一步

​用法

​项目

​Manifest

​编译

​远程项目与网络

​浏览器二进制与启动

​浏览器运行时

​调试协议

​开发服务器

​就绪契约

​控制通道

​日志

​创建

​其他所有情况

​折叠名与历史名

​下一步

用法

项目

Manifest

编译

远程项目与网络

浏览器二进制与启动

浏览器运行时

调试协议

开发服务器

就绪契约

控制通道

日志

创建

其他所有情况

折叠名与历史名

下一步