前端线上出现白屏如何排查问题所在，利用第三方的工具都有哪些

🧩 一、白屏问题总体排查思路

白屏就是「页面没有渲染出任何内容」或「闪一下后全白」。
常见原因可以分为 5 大类 👇：

类型	常见原因	说明
🧱 构建问题	打包错误、资源路径错误、publicPath 错、chunk 缺失	生产包没正确加载 JS/CSS
⚙️ 运行时 JS 报错	React/Vue 渲染时异常、接口数据为空、依赖未加载	页面初始化就崩溃
🌐 网络/环境问题	CDN 缓存、跨域、接口挂、DNS 解析错误	某些地区/环境才复现
🧩 DOM 渲染失败	挂载点丢失、SSR/CSR 混用	document.getElementById('root') 不存在等
🔒 安全策略限制	CSP、Mixed Content、HTTPS 问题	阻止脚本执行或资源加载

---

🧭 二、排查步骤与方法

🪣 Step 1：确认是否所有用户白屏还是部分用户

• 如果所有用户都白屏 → 大概率是构建或资源问题；
• 如果部分用户（特定浏览器、地区）白屏 → 网络或环境问题。

✅ 建议使用第三方监控平台做「实时错误分布统计」，下面第三节我会推荐。

---

🧩 Step 2：打开浏览器 DevTools（F12）排查

① Console 面板

看是否有：

• Uncaught TypeError、Cannot read property of undefined；
• SyntaxError: Unexpected token <（通常是接口返回 HTML，打包路径错）；
• Mixed Content、CSP blocked；
• chunk-xxx.js not found。

② Network 面板

检查：

• 是否有主资源（index.html / main.js / vendor.js）404；
• 请求是否走错域名；
• 返回是否是 HTML（可能 Nginx 配错，返回 index.html 而非 js 文件）。

⚡️技巧：如果某个 JS 文件请求结果是 HTML 内容，那就几乎可以确定是「路由或构建 publicPath 错」。

---

🧩 Step 3：在页面入口处加「兜底日志」

window.addEventListener('error', (e) => {
  console.error('Global Error:', e.message, e.filename, e.lineno);
});

window.addEventListener('unhandledrejection', (e) => {
  console.error('Promise Error:', e.reason);
});

线上配合日志上报（比如 Sentry/Fundebug）可快速定位首个 JS 报错点。

---

🧩 Step 4：灰度对比 / 回滚验证

• 使用 CI/CD 工具（Jenkins、GitLab CI、Vercel）快速回滚上一个稳定版本；
• 如果回滚后正常 → 说明是最新构建包或配置改动导致；
• 对比两次构建产物中的 index.html 与 manifest.json 差异。

---

🧩 Step 5：分析构建产物

• 检查打包产物目录中是否有所有 chunk；
• 打开 main.js，看首屏渲染是否依赖异步 import；
• 检查打包后的 publicPath 是否为正确的线上 CDN 路径；
• 如果使用 Vite / Webpack，要确认 base 或 output.publicPath 与部署路径一致。

---

🧰 三、第三方监控与排查工具推荐

这些工具能帮你 自动采集白屏时的错误堆栈、网络情况、设备环境，定位速度比人工快十倍以上。

---

🧿 1. Sentry

• ✅ 开源且功能最强（前端 + 后端统一）

• 自动捕获：

  • JS 运行错误（带 sourceMap 解析）
  • Promise 未捕获异常
  • 性能指标（LCP、FID、CLS）
  • 用户设备 / URL / 版本信息

• 支持 React、Vue、Next、Vite、Webpack 等框架

📦 示例集成（React）：

npm install @sentry/react @sentry/tracing

import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: "https://your-dsn.sentry.io/project",
  integrations: [new Sentry.BrowserTracing()],
  tracesSampleRate: 1.0,
});

💡 白屏时能直接看到第一个抛错的文件和行号。

---

🧩 2. Fundebug

• 轻量国产方案，配置简单；
• 支持上报 JS 错误、资源加载错误、API 错误；
• 对国内访问延迟低；
• 支持微信小程序、React、Vue。

📦 用法：

fundebug.apikey = 'your-key';
fundebug.notifyError(new Error('Test'));

---

🧠 3. LogRocket / SessionStack

• 能录制用户操作回放（点击、路由、控制台、网络请求）；
• 白屏时可以“还原出问题前的画面”；
• 非常适合复杂前端产品。

---

📊 4. 前端性能 & 白屏检测

如果你想监控「白屏时间」和「首屏加载性能」：

工具	功能	用法
Web-Vitals	监控 LCP / FID / CLS	npm i web-vitals
PerformanceObserver	自定义白屏时间指标	监听页面绘制时机
Aliyun ARMS 前端监控	白屏检测 + 错误采集 + 性能分析	阿里云一体化监控平台

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.name === 'first-contentful-paint') {
      console.log('白屏时间:', entry.startTime);
    }
  }
}).observe({ type: 'paint', buffered: true });

---

⚡️ 5. 浏览器端可视化 SDK

工具	特点
FullStory	用户操作录屏，白屏重现
TrackJS	错误统计 + 版本映射
BugSnag	稳定性监控、版本对比分析
阿里 ARMS / 腾讯云 CLS	可与业务日志结合使用

---

🧩 四、综合最佳实践推荐（可落地）

类别	工具	作用
错误捕获	Sentry / Fundebug	捕获 JS 报错堆栈
用户回放	LogRocket / SessionStack	重现白屏前行为
性能监控	Web-Vitals / ARMS	监控白屏时间、FCP
资源检测	自定义 heartbeat SDK	检测 JS/CSS 404
构建校验	CI 静态检查	打包前检测 publicPath / hash 变化

---

🧩 五、实际项目中建议

比如你做的“性能平台”项目（React + AntD + ECharts）：

1. 集成 Sentry 捕获首屏 JS 报错；

2. 用 ARMS 或 Web-Vitals 记录白屏时间；

3. 用 Nginx 日志 + SourceMap 对齐资源加载；

4. 配置自定义兜底页面：

   window.addEventListener('error', () => {
     document.body.innerHTML = '<div>页面出错了，请刷新重试。</div>';
   });
   

5. CI/CD 流程中，自动验证：

   curl -I https://yourdomain/main.js
   # 检查是否返回 200
   

---