Docker/uniapp/youjiala/src/md/error-handling.md

全局错误边界（未捕获异常与 Promise 拒绝的兜底）

适用范围：src/common/global-error.ts、src/App.vue 的 setupGlobalErrorBoundary() 调用、src/common/http.interceptor.ts 的"已提示"标记。 本文规定"什么错误由谁提示用户"，避免同一个故障弹两遍、或者干脆一声不响。请求层本身的链路见 page-routing.md，地址取值见 environment.md。

---

1. 为什么必须有

uni-app 没有 vue-router 那种 router.onError，也没有全局 app.config.errorHandler 的成熟落点：

• 页面里一个没 catch 的 promise，只会在控制台留一行，用户看到的是"点了没反应"；
• 运行时抛错若发生在异步回调里，可能连错误页都进不去。

所以本项目的兜底是 App 级两个钩子 + 一个上报模块：保证"控制台一定有记录，用户按需得到一次轻提示"。

2. 数据流与职责

页面 / service 漏 catch
  -> 错误来源（按端不同，见 §2.1）
       uni App 钩子：onError(err) / onUnhandledRejection({ reason, promise })
       H5 额外兜底：window "error" / "unhandledrejection" 监听
  -> setupGlobalErrorBoundary()（src/common/global-error.ts，在 App.vue setup 顶层调用一次）
  -> reportGlobalError(error, source)
       1) console.error 记全量原始错误（永不省略）
       2) 带"已提示"标记  -> 到此为止，只留日志
       3) 文案在 3s 内已提示过 -> 静默（去重）
       4) DEV  -> 排队弹 uni.showModal，显示来源与详情前 300 字
          PROD -> uni.showToast 一句通用文案

位置	负责什么
App.vue	只在 setup 顶层调一次 setupGlobalErrorBoundary()，不写判断逻辑
common/global-error.ts	钩子注册、H5 window 兜底、文案提取、去重、弹窗排队
common/http.interceptor.ts	决定"这一处是否已经打扰过用户"，并给错误打标记
页面 / 业务代码	能处理就自己 catch 并处理；处理不了就别 catch，交给边界

钩子注册必须放在 App.vue 的 setup 顶层：onError / onUnhandledRejection 要把回调绑到 App 实例上，放进 onLaunch 的回调里就离开了 setup 上下文。

onUnhandledRejection 只把 event.reason 传下去（不是整个 event）：类型里 reason 声明为 string，真机常常是 Error 对象，传原物才能让 describe() 拿到 message；describe() 也支持再往里挖一层（认 reason 字段），所以哪怕误传整个事件对象也不会掉进 [object Object]。

2.1 平台派发差异（H5 实测，不是抄文档）

端	谁派发 uni 钩子	够不着的错误	本项目的处理
H5	onError 只由 Vue 的 app.config.errorHandler 触发（组件渲染 / 生命周期里的同步错误）；onUnhandledRejection 在 uni-h5 全文没有派发点（搜 unhandledrejection 命中 0）	setTimeout / 事件回调里抛出的异常、所有 Promise 拒绝	额外挂 window 的 error / unhandledrejection 监听
微信小程序	由小程序运行时派发 App.onError / App.onUnhandledRejection（本轮未在真机/开发者工具实测）	需 capture 阶段才收得到的资源加载错误（未接）	uni 钩子覆盖主链路，§8 列了待办
App	由 uni-app 运行时派发（同样未实测）	同左	uni 钩子覆盖主链路

第一轮实测的教训就在这里：只在 App.vue 里注册 uni 钩子时，浏览器控制台能看到裸的 边界探针-error，但 [global:*] 一条都没出现、弹窗一次没弹 —— 钩子注册成功≠会被触发。所以 H5 的 window 兜底是必需项，setupGlobalErrorBoundary() 用 typeof window 判断只在浏览器里挂，小程序 / App 端自动跳过，windowFallbackInstalled 保证 HMR 重复执行也不会叠监听。

3. 三条纪律

1. 已提示过的不再打扰。 请求层已经弹过 toast/modal、或已经跳到登录页/403 页的错误，用 markErrorNotified(err) 打标记，边界见到标记只写日志。
2. 同一文案 3 秒内只提示一次。 去重按文案分桶（lastShownAt: Map<string, number>），记录表上限 64 条，超限时清掉超过 30 秒的旧项，长时间运行不会无限增长。
3. 只记录与提示，绝不吞错误。 该 throw 的照旧 throw，边界不负责"让程序继续跑"。否则故障会被藏进日志，排查时连"到底报没报"都区分不出来。

markErrorNotified 原样返回入参，所以能内联使用：

import { markErrorNotified } from "@/common/global-error";

throw markErrorNotified(new Error(bizMsg));
reject(markErrorNotified(err));

4. 请求层哪些站点打了标记

describe() 依次尝试 message / errMsg / errorMessage / msg / Message 取值，取不到就 String(error) 兜底，因此字符串型错误也能出文案。

站点	是否标记	原因
Failed to connect / request:fail	仅当 meta.toast 打开	提示由 meta.toast 决定；关掉提示时把兜底交还给边界
401 无登录态 → 跳登录页	标记	页面已经跳走，等于已告知
刷新令牌失败 → goLogin	标记原错误对象	保留 status 供调用方分支，只补标记
403 → 跳 403 页	标记	403 页会列出缺哪条权限，不需要再弹一次
非 2xx 通用分支	仅当 meta.toast 打开	err.status / err.data 保持不变
业务异常（ValidatedException / ServiceErrorException）	标记	detectBusinessException 内部已经 modal/toast
uploadFile 状态码异常 / 网络失败 / 业务异常	标记	三处都先 notifyError 再 reject
downloadFile JSON 错误体 / 非 2xx	标记	已提示
downloadFile 的 writeFile / openDocument 失败	不标记	这两处原本静默失败，正是要靠边界补提示
downloadFile 内部 uni.request 网络失败	不标记	没有任何提示动作

5. 业务代码怎么写

• 想让用户看到失败：直接 await，别 catch。边界会记日志并在生产给一句轻提示。
• 自己有能力恢复（重试、占位、表单标红）：自己 catch，处理完就别再抛；此时边界看不到这个错误，符合预期。
• 既要处理又要留痕：catch 里 console.error 后按需 markErrorNotified(err)，防止上层再抛时重复提示。
• 禁止 try { ... } catch { } 空吞。确实要忽略的错误，写成 catch { /* 说明为什么可以忽略 */ } 并在注释里给出理由。

6. 两端表现差异

场景	DEV（import.meta.env.DEV）	生产构建
未捕获错误	showModal：标题带来源（error / rejection），正文是错误文案前 300 字	showToast："操作未成功，请稍后重试"
已提示过的错误	只有 console.error	只有 console.error
同文案连续报错	首条弹窗，其余 3 秒内静默	首条 toast，其余 3 秒内静默

开发期弹窗是刻意的："看到了但没提示"和"确实没报错"必须能一眼区分。生产提示不带内部术语与堆栈，详情只在控制台。

弹窗必须排队：H5 的 <uni-modal> 是单例节点，连续两次 showModal 会原地改写同一个框，用户只看得见最后一条（实测过）。showDevModal() 因此按时间槽排队——每条占用最多 MODAL_MAX_HOLD_MS = 5000ms，到点没点"确定"也放行下一条，既不丢展示也不会把后续错误堵死。

7. 验证记录与配方

7.1 已完成的 H5 实测（2026-10-13，登录页临时探针）

探针：onLoad 里 600ms 抛 new Error("边界探针-error")、900ms 产生 Promise.reject(new Error("边界探针-rejection"))。验证完已删除。

检查项	修复前	修复后实测
[global:error] 日志	无	1 条（window error 监听）
[global:rejection] 日志	无	1 条（window unhandledrejection 监听）
弹窗标题	一次都没弹	未捕获错误（error） → 未捕获错误（rejection）
排队时刻	—	第二条在 t≈5.6s 出现（第一条 t≈0.6s + 5s 时间槽），实测与 MODAL_MAX_HOLD_MS 一致
重复提示	—	无：uni 钩子与 window 监听没有叠加打两遍，uni-modal 节点数恒为 1，无多余 toast

7.2 复现配方

1. 任意页面的 onLoad 里临时加一句 setTimeout(() => { throw new Error("边界探针"); }, 600); 与一句 setTimeout(() => { Promise.reject(new Error("边界探针-rejection")); }, 900);；
2. H5 跑 npm run dev，强制整页刷新（env / App.vue 改动不走热更）：应看到两条 [global:*] 日志与两个先后出现的弹窗；
3. 换成发一个必然失败的请求：应只有请求层那一次提示，边界只留日志（说明"已提示"标记生效）；
4. 小程序 / App 端：用微信开发者工具与 HBuilderX 各跑一次同样两个探针，确认 [global:*] 日志是否出现 —— 这一步还没做过，结果请回填 §8。

npm run type-check 与 npm run lint 只能证明代码可编译，不能证明钩子被触发；改完这块至少跑一遍第 1、2 步。

8. 已知缺口

• 小程序 / App 端运行时未实测：H5 已钉死（§7.1），另两端只做到"构建产物里含边界代码"。§7.2 第 4 步跑完前，不能宣称三端都兜住了。
• 资源加载错误没接：img / script 404 的 error 事件不冒泡，需要 window.addEventListener("error", handler, true)（capture 阶段）才收得到，目前未挂。
• 页面级错误未接管：onError 是 App 级的，某个页面自己用 errorCaptured 拦截后就不会冒到这里（目前项目里没人用 errorCaptured）。
• 提示文案未国际化："操作未成功，请稍后重试" 与弹窗标题都是硬编码中文，接多语言时应改走 vue-i18n，与 src/locale/lang 一起维护。
• 生产 toast 文案过于笼统：刻意不带细节，但如果要做错误上报（按 source + 文案指纹聚合），reportGlobalError 是唯一收口点，加上报只改这一处。