一、 Chrome 扩展错误收集机制与原理 (Why)

在 Chrome 扩展的生命周期管理中，开发者经常会注意到扩展管理页面 (chrome://extensions) 偶尔会弹出醒目的红色“错误”按钮。这种红色警示并非随意出现，其核心触发机制主要归结为以下两种情况：

1. 显式调用了 console.error(...)：Chromium 浏览器引擎设计上会对扩展程序上下文中的所有 console.error 调用进行拦截与统计。任何在扩展脚本中主动触发的 console.error，无论其内容是何，都会被系统视为扩展运行时中发生的“崩溃”或“错误”。
2. 存在全局未捕获的 Promise 异常：JavaScript 中的 Promise 异步操作若未能通过 .catch() 方法妥善处理其拒绝（rejection）状态，便会触发全局的 unhandledrejection 事件。这一事件在扩展环境中同样会被 Chromium 捕获，并视为未处理的运行时错误，从而导致红色错误提示的出现。

需要特别强调的是，诸如 503（服务器算力繁忙）、401（API Key 未配置或鉴权失败）、网络超时 等常见的业务网络异常，本质上属于可恢复的外部服务通信问题。这些问题并非扩展程序自身的代码逻辑错误或崩溃，因此绝不应该被浏览器判定为插件本身的程序崩溃，进而触发误导性的红色错误提示。将这些外部因素导致的瞬时问题与内部代码缺陷混淆，不仅会给开发者带来不必要的困扰，也会影响用户对扩展稳定性的感知。

---

二、 解决方案与重构落地 (How)

针对上述问题，我们设计并实施了一套全面的错误处理与重构方案，旨在彻底净化 Chrome 扩展管理页面的错误提示，同时确保开发者和用户能够精准地获取到有价值的错误信息。

1. 彻底屏蔽 Chrome 插件管理页面的红标错误

核心策略是在运行时层面进行错误拦截与重定向，避免业务异常上报至浏览器原生错误机制。

• 在 [runtime-error-filter.ts] 文件中（路径示例：src/lib/utils/runtime-error-filter.ts）：
  • 拦截全局未捕获 Promise 拒绝：通过监听 unhandledrejection 事件，我们能够捕获所有未被 .catch() 处理的 Promise 拒绝。对于这些拒绝，我们会进行分析判断，如果是第三方异步请求（如 Fetch API 或 Axios 等）导致的业务级异常，则将其进行内部消化或转换为更柔和的日志输出，防止其上报至 Chrome 扩展管理界面。
  • 智能重定向业务异常的 console.error：我们实现了一个代理机制，劫持了 console.error 方法。凡是涉及 AI 服务（如 OpenAI、Gemini）、外部网络请求、特定 HTTP 状态码（如 503、401、404）等业务逻辑层面可预期的错误，系统会自动将其从 console.error 级别降级，并转换为高亮警示的 console.warn 或自定义日志输出。这样既保留了错误信息的可追溯性，又避免了触发浏览器层面的“硬性”错误判定。
  • 效果：经过这套过滤和重定向机制，Chrome 插件管理页面 (chrome://extensions) 彻底恢复干净，再也不会出现因业务网络异常或可恢复性错误导致的红色错误提示！ 开发者可以专注于真正的代码逻辑问题，而非被外部服务波动所干扰。

2. 在插件 DevTools Console 中完整保留输出

尽管屏蔽了管理页面的红标错误，我们绝不会丢失任何有价值的错误细节。所有错误信息会以开发者友好的方式呈现在插件的 DevTools Console 中。

• 在 [AiAssistantFloat.tsx] 文件以及错误过滤层中：
  • 以 %c[AI 辅助服务异常] 彩色标签输出高可见度日志：为了让开发者能够快速识别和定位问题，我们将业务异常日志统一加上醒目的彩色前缀，例如在控制台中输出 [AI 辅助服务异常] 标签，并使用 CSS 样式使其高亮显示。
  • 完整保留原始的 Error 对象和全部调用栈（Stack Trace）：在输出日志时，我们确保会将原始的 Error 对象完整打印出来，包括其 message、name 以及最关键的 stack 属性。这意味着开发者在 F12 控制台排查问题时，所有错误细节、触发位置和调用链都一清二楚，极大地提升了调试效率。

3. 错误精准呈现在插件 UI 右上角 (Toast)

为了提升用户体验，我们将业务错误信息以人性化、易理解的方式直接反馈给用户，而非仅仅停留在开发者控制台。

• 对错误原因进行人性化分类翻译：
  • 503 / 算力繁忙：当遇到 503 HTTP 状态码时，右上角弹窗的标题会明确显示为 AI 服务瞬时繁忙 (503)。描述部分会提供清晰的用户指引：“官方模型服务器瞬时算力过载，请 3~5 秒后点击重试，或在上方下拉菜单中切换其他模型”。
  • 401 / 鉴权问题：针对 401 状态码，系统会提示用户检查其 API Key 设置，例如：“API Key 无效或未配置，请前往设置页检查您的 API Key。”
  • 404 / 模型不存在：如果请求的模型资源不存在，则会提示用户切换推荐模型：“请求的模型不存在，请尝试切换其他推荐模型。”
  • 网络/超时：当出现网络连接问题或请求超时时，会提示用户检查网络或代理状态：“网络连接异常或请求超时，请检查您的网络设置或代理状态。”
• 右上角弹出的错误卡片配置了 duration: Infinity 和关闭按钮，常驻在右上角直到用户手动点击关闭。这种设计确保了用户不会错过任何重要的错误提示，避免了“一闪而过”导致的信息遗漏，从而提升了用户对问题的感知和解决能力。

---

三、 构建验证

为了确保上述重构方案的稳定性和正确性，我们执行了严格的构建和类型检查流程：

• npx tsc --noEmit：此命令用于运行 TypeScript 编译器进行类型检查，但不生成任何输出文件。执行结果显示为 0 错误，这验证了代码库的类型安全性和一致性，确保在编译阶段不会引入潜在的类型问题。
• npx wxt build：使用 WXT 构建工具进行生产环境打包。构建过程成功完成，耗时 9.29s。这表明整个扩展项目能够顺利编译并打包成可部署的生产版本。刷新扩展后即可体验到上述优化后的错误处理机制。