补齐非 console.error 类 H5 报错的观察通路
排查「H5 有输出但 Safari 看不到」时发现,即便绕开 Safari 只看 Xcode,也有三类
故障是完全静默的:
1. 资源 404(<script>/<img>/<audio> 加载失败)
error 事件只在元素自身触发且不冒泡,原先 addEventListener('error', fn) 收不到。
改为捕获阶段 (capture=true),JS 异常的 ev.target 是 window,据此在同一 listener
内分流 onerror / resourceerror 两类。缺图缺 js 是 H5 最常见的线上故障,此前零信号。
2. WebView 加载失败(didFailProvisionalNavigation / didFail)
两个 VC 的 WKNavigationDelegate 此前只实现了 didFinish。AppSchemeHandler 找不到
index.html、子游戏 zip 解压残缺时,splash 永不淡出、卡在启动图,Xcode 无任何输出。
3. WebContent 进程终止(webViewWebContentProcessDidTerminate)
canvas 游戏 JSC OOM 被系统回收时页面白屏,同样静默。
⚠️ 只 log 不自动 reload —— 自动恢复是行为变化,msext 没有,不引入。
另:H5ErrorRelay.install 增加 label 参数,输出前缀从 [H5 xxx] 变为
[H5:lobby xxx] / [H5:subGame xxx]。同时存在多个 BridgedWebView 时原先分不清
日志来自谁,也就无法反推该在 Safari「开发」菜单里选哪个条目。
无契约影响:H5 可观察行为不变,新增回调仅记录不改流程。
Debug / Release 两个配置均已编译验证。
docs/H5-Debug-Guide.md §8.1 更新能力表,新增 §8.2 已知盲区 / §8.3 设计要点。
This commit is contained in:
+26
-8
@@ -238,17 +238,34 @@ Safari Web Inspector 是开发期主力,但有它够不到的场景:
|
||||
|
||||
`Source/Bridge/H5ErrorRelay.swift` 用 `WKUserScript(.atDocumentStart)` hook 住 console 与全局异常,通过 `webkit.messageHandlers.h5error` 转发到原生。**不改 H5 一行**(原则 A)。
|
||||
|
||||
| JS 侧 | Xcode 输出前缀 | 落 `Documents/diag.log` | 构建配置 |
|
||||
前缀里的 `lobby` / `subGame` 是 `BridgedWebView(label:)`,用来区分同时存在的多个 WebView——也用来反推该在 Safari「开发」菜单里选哪个条目。
|
||||
|
||||
| 来源 | Xcode 输出前缀 | 落 `Documents/diag.log` | 构建配置 |
|
||||
|-------|---------------|------------------------|---------|
|
||||
| `console.log` | `[H5 console.log]` | ❌ | **仅 Debug** |
|
||||
| `console.info` | `[H5 console.info]` | ❌ | **仅 Debug** |
|
||||
| `console.warn` | `[H5 console.warn]` | ✅ | Debug + Release |
|
||||
| `console.error` | `[H5 console.error]` | ✅ | Debug + Release |
|
||||
| `window.onerror` | `[H5 onerror]` | ✅ | Debug + Release |
|
||||
| `unhandledrejection` | `[H5 unhandledrejection]` | ✅ | Debug + Release |
|
||||
| `console.log` | `[H5:lobby console.log]` | ❌ | **仅 Debug** |
|
||||
| `console.info` | `[H5:lobby console.info]` | ❌ | **仅 Debug** |
|
||||
| `console.warn` | `[H5:lobby console.warn]` | ✅ | Debug + Release |
|
||||
| `console.error` | `[H5:lobby console.error]` | ✅ | Debug + Release |
|
||||
| 未捕获 JS 异常 | `[H5:lobby onerror]` | ✅ | Debug + Release |
|
||||
| 未处理的 Promise rejection | `[H5:lobby unhandledrejection]` | ✅ | Debug + Release |
|
||||
| 资源 404(`<script>`/`<img>`/`<audio>`) | `[H5:lobby resourceerror]` | ✅ | Debug + Release |
|
||||
| WebView 首次/提交后加载失败 | `[WebView:lobby] …加载失败` | ✅ | Debug + Release |
|
||||
| WebContent 进程终止(白屏) | `[WebView:lobby] ⚠️ WebContent 进程终止` | ✅ | Debug + Release |
|
||||
|
||||
设计要点:
|
||||
### 8.2 仍然抓不到的(已知盲区)
|
||||
|
||||
| 场景 | 为什么抓不到 |
|
||||
|------|------------|
|
||||
| 被 H5 自己 `try/catch` 吞掉的异常 | 根本不冒到 window。本包里 `12_Logic.js:254` / `gameabc.min.js:2175` 就是 catch 后用 `console.log(e.stack)` 打印 → 只在 Debug 的 `[H5:… console.log]` 里能看到 |
|
||||
| iframe 内的异常 | `WKUserScript(forMainFrameOnly: true)`,只 hook 主框架 |
|
||||
| 弹层(`OverlayViewController`)的 JS | 第三方外链,按设计不挂 relay |
|
||||
| 跨域脚本的异常细节 | 浏览器安全策略统一报 `Script error.`,无行号无堆栈 |
|
||||
| 原生 handler 内部抛错 | 属原生侧,走 `BridgeBus` 自己的 `diagLog` |
|
||||
|
||||
### 8.3 设计要点
|
||||
|
||||
- **资源 404 必须开捕获阶段**:`<script>`/`<img>`/`<audio>` 的 error 事件只在元素自身触发且**不冒泡**,`addEventListener('error', fn)` 收不到,必须 `addEventListener('error', fn, true)`。JS 异常的 `ev.target` 是 `window`,据此在同一 listener 内分流两类
|
||||
- **导航层失败只 log 不自动 reload**:自动恢复是行为变化,msext 没有,不引入
|
||||
- **`log` / `info` 只在 Debug 注入**:Release 包不该为每条业务日志付一次 JS→Native IPC,也不该把 H5 内部输出暴露给外部审阅。`#if DEBUG` 在编译期就把这段 JS 从 `javaScriptSource` 里摘掉
|
||||
- **`log` / `info` 走裸 `print` 而非 `diagLog`**:`diagLog` 会同步落盘到 `Documents/diag.log`,而该 sink 无轮转、无大小上限(`BridgeBus.swift:47`)。一旦 §7 Q3 里的 `isDebugger` 被打开,收发包 firehose 灌进去会把设备磁盘吃光
|
||||
- **对象参数走 `JSON.stringify`**:大厅业务大量使用 `console.log(msg)` / `console.log(res)` 打整包,直接 `String(obj)` 只会得到无用的 `[object Object]`。循环引用时 stringify 抛错 → 回退 `String()` → 再抛则输出 `[unstringifiable]`
|
||||
@@ -265,3 +282,4 @@ Safari Web Inspector 是开发期主力,但有它够不到的场景:
|
||||
|------|------|
|
||||
| 2026-06-24 | 文档建立。落地 `BridgedWebView` / `OverlayViewController` 两处 `isInspectable` 补丁。 |
|
||||
| 2026-08-08 | 查明「Console 空」的首要原因是 H5 自带 `Game_Config.Debugger.isDebugger = false`,补进 §7 Q3。`H5ErrorRelay` 扩展 `console.log` / `console.info` 转发(Debug only)+ 对象参数 JSON 序列化,新增 §8.1。 |
|
||||
| 2026-08-08 | 补齐「非 H5 主动 console.error」的报错通路:资源 404(error 事件捕获阶段)、WebView 加载失败 / WebContent 进程终止(两个 VC 的 `WKNavigationDelegate`,此前完全没实现)。输出加 `lobby` / `subGame` 前缀。新增 §8.2 已知盲区、§8.3 设计要点。 |
|
||||
|
||||
Reference in New Issue
Block a user