故障排查能力
快速分诊流程
- 用一个目标(
--browser=chromium) 复现。 - 移除自定义 profile 与 binary 标志。
- 确认问题是出现在
dev、build还是两者都有。 - 一次修复一类错误(重启、依赖、路径或启动)。
快速诊断决策树
常见问题
需要重启的诊断
如果你看到”需要重启”的错误，停下来，重新运行extension dev。
典型触发：
- manifest 入口列表发生变化。
- 在
pages/或scripts/中增删文件。 - HTML 中结构性的脚本/样式条目变化。
缺少可选依赖
CLI 会按需安装一些集成(例如 Vue/Preact 的 refresh 工具、样式预处理器)。 如果 CLI 提示安装可选依赖：- 允许安装。
- 重启
extension dev。 - 在依赖安装完成后再运行。
浏览器二进制问题
如果目标浏览器启动失败：- 验证自定义 binary 路径(
--chromium-binary/--gecko-binary)。 - 确认浏览器目标与所提供的 binary 兼容。
- 退回到默认的
chromium目标以隔离配置问题。
build 跑通了但 preview 显示的是错误的代码
preview 会在 dist/<target> 存在时加载它，不存在时则退回到源码 manifest 所在的目录，因此缺少构建产物时它会运行未构建的源码，而不是直接失败。
- 运行
extension build --browser=<target>。 - 然后运行
extension preview --browser=<target>。
manifest 引用错误
如果构建报告缺少 manifest 文件：- 验证路径是否相对于 manifest 位置。
- 验证前导
/的用法(public-root 语义)。 - 确保文件确实存在于源码/public 位置。
Docker、开发容器与 Codespaces
在容器内运行时，开发服务器默认绑定到127.0.0.1，所以宿主机无法访问。
- 传入
--host 0.0.0.0绑定到所有网卡。 - 如果
8080被占用，使用--port 0让操作系统分配空闲端口。 - 如果在持续集成 (CI) 容器中浏览器连接缓慢或不稳定，可通过浏览器传输调优变量 提高连接超时。
scripts/ 文件夹中的 Node.js 脚本
如果构建失败并提示 scripts/ is a reserved folder in Extension.js，说明你在 scripts/ 特殊文件夹中放了 Node.js 文件。Extension.js 会用浏览器 content-script 运行时包装 scripts/ 中的每个文件，仅 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 页面上的热模块替换，因此页面会退回到整页重新加载。4.1.10 版本为这些页面开启了热模块替换，并从 URL 中移除旧参数。请升级：
- 运行
npx extension@latest dev使用最新 CLI，或者提升package.json中extension依赖的版本。
修复后仍被卡住
如果问题仍然存在：- 清理临时假设，从干净的终端会话开始重现。
- 缩减到最小的、仍能复现失败的 manifest/入口情况。
- 记录精确的命令与错误输出以便提交 issue。
调试检查清单
- 先用单个浏览器目标复现(
--browser=chromium)。 - 不带自定义 profile/binary 标志复现。
- 检查问题是否在
dev与build中都出现。 - 在同时修改 manifest 与入口文件时，一次只改动一处。