SuperAPI AI 工具集

stackblitz-common-errors

编程与开发

查看项目

更新于 10-16 07:06

技能介绍

用途

该技能用于诊断 WebContainer 相关的常见错误,围绕启动、隔离、Service Worker、依赖安装、进程、预览和浏览器等方面进行基于证据的排查。核心理念是按确定性诊断顺序推进,避免推测性重试,也不随意削弱安全头配置。

诊断顺序与主要能力

诊断遵循以下层次:浏览器能力、服务端响应头、生命周期归属、运行时事件、进程退出、依赖兼容性、预览行为。

关键判断契约包括:

  • SharedArrayBuffer 或 crossOriginIsolated 失败时,应从实际 HTML 响应中的 COOP/COEP 响应头入手,包括 304 行为。
  • 出现代理已释放或重复启动失败时,需要证明 boot() 是否运行了多次,包括 HMR 场景。
  • 依赖安装应保留退出码和受限输出;lockfile 有助于提升可重复性和启动速度。
  • 原生 Node 插件不可用,除非用 JavaScript 或 WebAssembly 实现替代方案。
  • 浏览器隐私控制可能阻断所需的 Service Worker 或第三方存储行为。
  • 预览失败应通过进程退出以及错误、端口、服务器就绪事件来排查。

使用方式

工作流程为:

  1. 用最小合成项目复现,并记录浏览器、URL、安全上下文和隔离状态。
  2. 检查最终文档响应头和缓存响应行为。
  3. 统计 boot 路径,追踪 HMR、导航和 teardown 归属。
  4. 捕获受限的运行时事件、启动的命令、退出码和最后有效输出行。
  5. 将依赖与 WebContainer 文档化约束对比,尤其是原生插件和安装行为。
  6. 只应用一个针对具体层次的修复,重复复现,并记录回滚与剩余浏览器差异。

工具使用纪律:可使用 Read、Glob、Grep 查找启动调用、响应头、运行时事件、进程处理和依赖清单;仅使用 WebFetch 获取当前官方 StackBlitz 或 WebContainers 文档;只有在识别出故障层后才使用 Write 或 Edit。

输出内容包括复现步骤、按层证据、根因或排序假设、已实施或建议的精确修复、验证结果、脱敏处理、回滚方式以及未解决的兼容性风险。

适用场景

适合需要在浏览器内运行 Node.js 环境的项目排查,例如 StackBlitz/WebContainers 项目的启动失败、隔离头配置问题、Service Worker 或第三方存储被浏览器隐私设置阻断、依赖安装卡住、预览无法出现等情况。也适合在 HMR 场景下定位重复启动或提前 teardown 的问题。

限制与边界

未经明确授权,不得禁用浏览器安全设置、广泛放宽 COOP/COEP 或 CSP、清除用户浏览器数据、替换依赖或更改生产托管环境。共享证据时必须对 API key、注册表 token、OAuth 信息、Cookie、源码内容和动态预览 URL 进行脱敏;私有包失败时只报告鉴权状态和包标识,不打印凭据值。

其他前提包括:需要可复现的 URL 或本地命令及受影响浏览器版本;需要检查应用代码、响应头和受限浏览器/运行时日志的权限;含敏感数据的项目应使用合成复现。

错误处理对应

  • SharedArrayBuffer 传输失败:验证安全上下文、COOP/COEP、匹配的启动选项和缓存响应头。
  • 代理被释放:查找重复启动或提前 teardown 路径,包括 HMR。
  • 安装卡住或失败:保留 lockfile 状态、退出码和受限输出,检查是否使用原生插件。
  • 预览始终不出现:将进程退出与端口、错误、服务器就绪事件关联起来。

暂未提供

关于该技能的具体收费方式、价格、支持平台版本、效果数据或额外安装步骤,资料中暂未提供。