背景介绍：一句“白屏”背后的暗流
如果你在社区里搜过“ChatGPT 打不开”，十有八九会蹦出一条鲜红的报错：
Application error: a client-side exception has occurred (see the browser console)
这条信息本身没给出任何业务线索，却足以让新用户直接关掉标签页。根据浏览器内核的统计，单页应用在首次加载阶段出现未捕获异常的概率约为 0.7%–1.2%，而 ChatGPT 类重度依赖流式接口的产品，比例还会再翻半倍。换句话说，每 1000 次访问里就有 10 个人看到白屏，其中一半会刷新，另一半直接流失。对前端来说，这不仅是体验分扣分，更是实打实的投诉工单。
错误分析：把一句提示拆成零件
1. 信息结构
Application error：Next.js 等框架在 production 模式下，把未被 Error Boundary 捕获的错误统一渲染成该字符串。a client-side exception has occurred：说明异常抛在浏览器端，而不是 500、502 之类的服务器状态码。(see the browser console)：提示开发者去控制台找更完整的stack trace。
2. 常见触发场景
网络抖动：流式接口返回
content-encoding: gzip，但中途被运营商重置，浏览器在decompress阶段抛net::ERR_INCOMPLETE_CHUNKED_ENCODING。API 返回非预期格式：后端把
text/event-stream写成了application/json，前端按EventStream解析直接JSON.parse崩溃。前端代码缺陷：数组越界、正则回溯爆栈、第三方库
polyfill冲突，甚至误把localStorage写满 5 MB 导致QuotaExceededError。浏览器插件注入：某些广告过滤脚本会把
window.fetch代理掉，结果response.body.getReader()调用时上下文丢失，抛出TypeError。
排查方法：把 DevTools 玩成“显微镜”
1. 复现与采样
- 打开无痕窗口，禁用扩展，先排除插件因素。
- 在 Network 面板勾选Preserve log，防止重定向把日志冲掉。
- 切换Online / Offline / Slow 3G，模拟弱网。
2. 控制台“三看”原则
看红色堆栈：展开
stack首行，定位文件名、行列号。若被压缩，点右键 →Add source map关联本地source-map。看异步上下文：勾选Pause on exceptions，在
catch之前断点，查看调用栈里的async链路。看全局事件：在 Console 执行
window.addEventListener('error', e => console.error('caught at window:', e))
可捕获未被ErrorBoundary兜住的旧式脚本错误。
3. 日志分级小技巧
把日志按颜色分组，一眼区分“致命”与“警告”：
const log = (level, ...args) => console[level](`%c[${level}]`, `color:${level==='error'?'red':'orange'}`, ...args);解决方案：把“异常”变成“体验”
1. React 错误边界（Error Boundary）
// ErrorBoundary.jsx import React from 'react'; export default class ErrorBoundary extends React.Component { state = { hasError: false, error: null }; static getDerivedStateFromError(error) { return { hasError: true, error }; } componentDidCatch(error, info) { // 1. 本地日志 console.error('[ErrorBoundary]', error, info); // 2. 远端日志 window.errorTracker?.captureException(error, { extra: info }); } reset = () => this.setState({ hasError: false, error: null }); render() { if (this.state.hasError) { return ( <div className="error-fallback"> <h3>页面开小差了</h3> <button onClick={this.reset}>再试一次</button> <details> <summary>技术细节</summary> <pre>{this.state.error?.stack}</pre> </details> </div> ); } return this.props.children; } }在_app.jsx最外层包一层：
<ErrorBoundary> <Component {...pageProps} /> </ErrorBoundary>2. Vue3 错误捕获
// main.js import { createApp } from 'vue'; import App from './App.vue'; const app = createApp(App); // 全局错误句柄 app.config.errorHandler = (err, vm, info) => { console.error('[Global]', err, info); window.errorTracker?.captureException(err, { extra: { vm: vm.$options.name } }); }; // 全局未处理 Promise window.addEventListener('unhandledrejection', e => { console.error('[UnhandledRejection]', e.reason); e.preventDefault(); // 阻止默认红色提示 }); app.mount('#app');3. 流式接口兜底
async function*Chat(prompt) { const reader = await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ prompt }), headers: { 'Content-Type': 'application/json' } }).then(r => { if (!r.ok) throw new Error(`Server ${r.status}`); return r.body.getReader(); }); const decoder = new TextDecoderStream(); try { while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value, { stream: true }); appendMessage(chunk); } } catch (e) { // 网络中断给出友好提示 appendMessage('\n\n(网络波动，已自动重连)'); // 可在此处做指数退避重试 } finally { reader.releaseLock(); } }避坑指南：别把“拍脑袋”当“最佳实践”
反模式 1：
try/catch一把梭，结果把错误吞掉，用户看不到任何反馈，调试也找不到日志。反模式 2：生产环境关闭
source-map，线上报错全是1.234行列号，排查等于盲猜。反模式 3：把
window.onerror写成alert(error)，在移动端会卡死主线程，体验负分。
生产调试技巧：
- 使用
Sentry / LogRocket / Fundebug之类 SaaS，自动上传source-map与userAgent，结合git commit做版本回溯。 - 灰度发布时，给 5% 用户打开
debug=1参数，前端动态降采样上传日志，平衡性能与可观测性。
进阶建议：让错误“可视化、可量化、可报警”
1. 自建轻量监控
class ErrorTracker { constructor({ dsn, sampleRate = 1 }) { this.dsn = dsn; this.sampleRate = sampleRate; } captureException(error, context) { if (Math.random() > this.sampleRate) return; fetch(this.dsn, { method: 'POST', body: JSON.stringify({ msg: error.message, stack: error.stack, url: location.href, ...context }), keepalive: true // 页面卸载时也能发 }); } } window.errorTracker = new ErrorTracker({ dsn: '/api/log', sampleRate: 0.3 });2. 与后端联调 checklist
- 统一
request-id：后端在响应头返回x-request-id，前端捕获异常时一并上报，方便两端对齐日志。 - 流式接口先返回
200再吐eventstream，不要先302再重定向，避免fetch丢失body。 - 对
CORS预检失败单独提示，别让用户刷新，直接引导关闭代理或切换网络。
延伸思考题
- 如果你的产品要支持离线模式，如何设计一套“本地缓存 + 错误队列”机制，保证弱网场景下用户输入不丢失？
- 错误采样率动态调整：当监控发现异常突增 300% 时，如何把采样率从 5% 自动提到 100%，并在恢复后降回？
- 在微前端架构里，子应用崩溃可能导致主应用雪崩，你会如何设计“子应用隔离 + 独立错误边界”方案？
文章里的代码片段都已在真实项目跑过，直接复制即可用。如果你也想亲手搭一个“能听会说”的 AI 对话应用，顺便把上面这些异常处理技巧全部演练一遍，可以试试我上周刚跟完的从0打造个人豆包实时通话AI动手实验。整个流程从申请火山引擎密钥到部署上线都有图文指引，连 Node 版本切换都写得明明白白，对前端同学相当友好。我这种“半吊子”后端水平也能一次跑通，相信你也可以。祝编码愉快，控制台永远只打印彩虹日志！
