coze-studio 前端错误治理实战深入解读 coze-arch/bot-error 错误处理包【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio导读在 coze-studio 这类大型 AI Agent 开发平台的前端工程中错误监控的准确性直接决定线上问题的可排查性。本文以仓库内 frontend/packages/arch/bot-error 包的官方文档 README.md 为主体结合其完整源码实现系统讲解如何通过coze-arch/bot-error定义可监控的业务错误CustomError、识别已归类的确定性错误Certain Error并借助 React Hook 统一捕获全局异常并接入 Slardar 监控。读完本文你将掌握一套可直接落地的前端错误分级、上报与兜底方案并理解其背后的识别链路与设计取舍。一、包定位与安装coze-arch/bot-error是 coze-studio 前端 arch 体系下的错误处理基础包核心目标是让业务方以极低成本抛出可监控的自定义错误同时让全局错误采集能够识别错误类型、避免重复上报并把真正未知的错误兜底到 jsError 统计中。其入口聚合在 src/index.ts对外暴露 5 个能力CustomError/isCustomError自定义错误类及类型守卫useErrorCatch全局unhandledrejection/ SlardarbeforeSend拦截 HookuseRouteErrorCatch路由级错误兜底 HookisChunkErrorWebpack 分块加载失败判定。安装采用 Rush Monorepo 的统一依赖管理方式仓库根目录由 rush.json 管理在项目目录下执行cd ${path/to/project} rush add coze-arch/bot-error从 package.json 可以看到它的运行时依赖设计coze-arch/bot-http提供isApiError、coze-arch/logger提供logger与reporter即 Slardar 上报通道以及axios提供isAxiosError。也就是说该包的错误识别能力建立在已有的 HTTP 错误封装与统一日志体系之上。二、CustomError面向监控的业务错误2.1 为什么需要自定义错误类原生Error抛出的异常会被前端监控统一统计为jsError噪音大、难以区分业务语义。CustomError的设计目的正是把业务主动抛出的、可预期的错误与未知的 JS 运行时错误区分开使用throw new CustomError(...)抛出的错误会上报到 Slardar 的自定义事件中业务方可按事件名进行监控处理不会被统计进 jsError。2.2 构造参数与源码实现CustomError的完整签名定义在 src/custom-error.tsexport class CustomError extends Error { constructor( public eventName: string, // 自定义事件名用于监控检索 public msg: string, // 错误描述等价于 Error.message public ext?: { customGlobalErrorConfig?: { title?: string; // 自定义兜底 UI 标题 subtitle?: string; // 自定义兜底 UI 副标题 }; }, ) { super(msg); this.name CustomError; this.ext ext; } }三个参数的作用eventName监控事件名上报时作为自定义事件维度是排查问题的关键索引msg错误信息与Error.message保持一致便于现有错误链路兼容ext可选附加配置其中customGlobalErrorConfig可用于自定义全局错误兜底页的标题与副标题文案。使用方式与 README 一致import { CustomError } from coze-arch/bot-error; throw new CustomError(parmasValidation, empty copy);对应的单元测试见tests/custom-error.test.ts它验证了三个关键不变量customError是Error的实例customError.name CustomErrorcustomError.eventName、customError.msg与customError.message三者与构造入参一致。2.3 isCustomError双重判定的类型守卫import { isCustomError, CustomError } from coze-arch/bot-error; const myError new CustomError(parmasValidation, empty copy); console.log(isCustomError(myError)); // 输出trueisCustomError不仅判断instanceof还额外检查name CustomErrorexport const isCustomError (error: unknown): error is CustomError error instanceof CustomError || (error as CustomError)?.name CustomError;源码注释明确指出这一设计原因Slardar 的beforeSend捕获到的错误需要靠.name判断错误类型。当错误跨 iframe / 多副本环境传播或经序列化后不再是原类的实例时name字符串判断依然有效这保证了错误识别在前端监控链路上的健壮性。三、useErrorCatch全局错误兜底 HookuseErrorCatch是 README 明确说明的 React Hook用于在组件中捕获和处理错误包含两个职责监听全局unhandledrejection、error事件上报相关内容由业务侧自行补充对于已知错误上报自定义事件进行监控。其完整实现见 src/use-error-catch.ts典型用法如下import { useErrorCatch } from coze-arch/bot-error; import { slardarInstance } from 你的监控实例; function App() { useErrorCatch(slardarInstance); return {/* 应用内容 */}/; }3.1 第一道防线捕获未处理的 Promise rejectionHook 通过window.addEventListener(unhandledrejection, ...)注册监听组件卸载时移除避免内存泄漏。回调内部调用event.promise.catch取出真实错误并做两件事用loggerWithScope.info记录一条诊断日志scope 为use-error-catchnamespace 为bot-error调用sendCertainError(error, reason ...)尝试按确定性错误处理若错误无法识别则回退上报ReportEventNames.Unhandledrejection事件并标记reportJsError: true。3.2 第二道防线拦截 Slardar 上报前的重复噪音第二个useEffect在 Slardar 实例上注册beforeSend拦截器const beforeSlardarSend (e: any) { const error e?.payload?.error; if (error isCertainError(error) getErrorName(error) ! notInstanceError) { sendCertainError(error); return false; // 已归类处理阻止默认 jsError 上报 } return e; // 未知错误放行给默认统计 };这条链路非常关键凡是能被识别为确定性错误CustomError / AxiosError / ApiError / ChunkLoadError的异常都在发送前被截胡转为自定义事件上报并返回false阻止其落入 jsError 统计只有完全未知的错误才继续走默认通道。这正是 README 所述不会统计到 jsError在实现层的体现。四、错误识别内核certain-error 分级链路虽然 README 只重点介绍了CustomError与useErrorCatch但整个包的分级能力核心在 src/certain-error.ts。理解它才能真正用好这套错误治理方案。4.1 五种确定性错误Certain Error源码通过一张有序的错误判定表完成识别顺序即优先级判定函数错误名说明isCustomErrorCustomError业务方主动抛出的自定义错误isAxiosErroraxios 提供AxiosErrorHTTP 状态码非 2xxisApiErrorcoze-arch/bot-http提供ApiError状态码 2xx 但业务码非 0isChunkErrorChunkLoadErrorWebpack chunk 加载失败!(error instanceof Error)notInstanceError未继承 Error 的异常如表单校验对象这些类型统一收口在 src/const.ts 的CertainErrorName联合类型中并配套定义了统一上报事件名枚举ReportEventNamesexport enum ReportEventNames { ChunkLoadError chunk_load_error, // Webpack chunk 加载失败 Unhandledrejection unhandledrejection, // 异步错误兜底 GlobalErrorBoundary global_error_boundary, // 全局错误边界 NotInstanceError notInstanceError, CustomErrorReport custom_error_report, // 统一上报自定义错误 }4.2 各类错误的差异化处理策略handleCertainError根据识别结果执行不同策略体现了分级治理的设计CustomError双事件上报——先按custom_error_report统一事件补录携带originEventName、originErrorMessage原始信息再按业务方传入的eventName单独上报既保证监控可聚合又保留业务维度ApiError / AxiosError直接过滤因为这类错误在 HTTP 层已有自身的错误处理与监控避免重复上报ChunkLoadError不进入业务错误通道改用reporter.info记录静态资源异常信息name/message/stack由 Slardar 静态资源异常统计承接notInstanceError尝试JSON.stringify序列化错误对象后按notInstanceError事件上报序列化失败则用占位文案兜底保证任何形态的错误都能被记录。4.3 对外判定 APIexport const getErrorName (error: Error) { /* ... */ }; export const isCertainError (error: Error) errorName ! unknown; export const sendCertainError (error, handle?) { /* ... */ };getErrorName(error)按优先级查表返回错误名或unknownisCertainError(error)是否属于五类已知错误sendCertainError(error, handle?)已知错误走handleCertainError未知错误则调用handle?.(error?.message)让调用方自行兜底上报。useErrorCatch与useRouteErrorCatch都是在这三个 API 之上封装的。五、useRouteErrorCatch路由级错误兜底源码还额外提供了路由错误兜底 Hook src/use-route-error-catch.ts可作为全局 ErrorBoundary 的配套import { useRouteErrorCatch } from coze-arch/bot-error; import { useRouteError } from react-router-dom; function RouteErrorFallback() { const error useRouteError(); useRouteErrorCatch(error); return div页面出错了/div; }其行为依赖error变化触发上报若error不是Error实例如 React Router 传入的对象或字符串则包装为new CustomError(ReportEventNames.GlobalErrorBoundary, ...)统一收敛到global_error_boundary事件已知错误交由sendCertainError分级处理未知错误则上报global_error_boundary事件并标记reportJsError: true作为全局错误边界捕获的兜底记录。六、ChunkLoadError 识别细节src/source-error.ts 提供对分块加载失败的三种识别覆盖 Webpack 与三方脚本两类场景export const isWebpackChunkError (error: Error) error.name ChunkLoadError; // 匹配 Loading chunk 3 failed. (error: ) export const isThirdPartyJsChunkError (error: Error { type?: string }) error.message?.startsWith(Loading chunk); // 匹配 Loading CSS chunk 8153 failed. () export const isCssChunkError (error: Error) error.message?.startsWith(Loading CSS chunk); export const isChunkError (error: Error) isWebpackChunkError(error) || isThirdPartyJsChunkError(error) || isCssChunkError(error);由于 chunk 加载失败时错误对象形态多变name 可能是ChunkLoadError也可能只有 message 前缀特征因此采用name 判断 message 前缀匹配的多重策略识别后交给certain-error走静态资源异常统计通道。七、工程化配套与测试保障该包遵循 arch 体系的标准工程规范package.json 提供linteslint、testvitest、test:cov覆盖率脚本构建配置见 tsconfig.build.jsonRush 构建配置见 config/rush-project.json。针对每个核心能力都有对应的单测可以直接作为使用样例阅读custom-error.test.ts验证CustomError的实例关系、字段一致性及isCustomError的正反判定certain-error.test.ts验证确定性错误识别与分级处理source-error.test.ts验证 chunk 错误的多重识别use-error-catch.test.ts 与 use-route-error-catch.test.ts验证两个 Hook 的事件监听、上报拦截与清理逻辑。八、最佳实践小结综合 README 与源码在 coze-studio 前端项目中落地这套错误治理方案建议遵循以下模式业务可预期错误一律抛CustomErrorthrow new CustomError(事件名, 描述)让监控落在自定义事件而非 jsError配合ext.customGlobalErrorConfig可定制兜底 UI 文案应用根部挂载useErrorCatch(slardarInstance)一次性获得unhandledrejection兜底与 SlardarbeforeSend拦截未知错误才落入 jsError路由级配合useRouteErrorCatch在路由错误组件中上报global_error_boundary事件补齐渲染链路不需要重复判断错误类型isCertainError/getErrorName已统一覆盖 CustomError、AxiosError、ApiError、ChunkLoadError 与 notInstanceError 五类业务侧只需关注自己的上报补充逻辑。通过已知错误分级处理 未知错误兜底统计的双通道设计coze-arch/bot-error帮助前端团队在保证错误不丢失的同时大幅降低监控噪音让每一条异常都能被准确归因。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考