故障排查能力
快速分诊流程
- 用一个目标(
--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 依赖已有的构建产物。
- 运行
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/)。详情请参见特殊文件夹。
修复后仍被卡住
如果问题仍然存在：- 清理临时假设，从干净的终端会话开始重现。
- 缩减到最小的、仍能复现失败的 manifest/入口情况。
- 记录精确的命令与错误输出以便提交 issue。
调试检查清单
- 先用单个浏览器目标复现(
--browser=chromium)。 - 不带自定义 profile/binary 标志复现。
- 检查问题是否在
dev与build中都出现。 - 在同时修改 manifest 与入口文件时，一次只改动一处。