Vollständiger Leitfaden zum Frontend-Fehlermonitoring: Sentry, SourceMap und benutzertransparente Ausnahmeerfassung

前端工程

Warum Frontend-Fehlermonitoring unverzichtbar ist

Benutzer, die auf leere Bildschirme, nicht reagierende Schaltflächen oder API-Fehler in der Produktion stoßen — wenn Sie davon nichts wissen, können Sie es nicht beheben. Frontend-Fehlermonitoring ist die Brücke, die reale Benutzererfahrung mit dem Bewusstsein der Entwickler verbindet.

Kosten ohne Monitoring Nutzen mit Monitoring
Bugs nur durch Benutzerbeschwerden entdeckt Echtzeit-Anomalieerkennung, minutenbezogene Reaktion
Nicht reproduzierbare sporadische Probleme Vollständige Stack Traces + Verhaltenswiederholung des Benutzers
Produktionsvorfälle, die Stunden andauern Automatische Alarmierung, drastisch reduzierter MTTR
Auf Vermutungen basierende Fehlerbehebungen Datengetrieben, präzise Lokalisierung

Die fünf Quellen von Frontend-Fehlern

1. Syntax- und Laufzeitfehler

// ReferenceError: x is not defined
console.log(x);

// TypeError: Cannot read properties of undefined
const user = undefined;
user.name;

2. Ressourcen-Ladefehler

// Ladefehler bei Bildern, Skripten, Stylesheets
const img = new Image();
img.src = '/broken-image.png';
img.onerror = () => {
  trackError({ type: 'resource', tag: 'img', src: img.src });
};

3. Nicht erfasste Promise-Ausnahmen

// Der am leichtesten übersehene Fehlertyp
fetch('/api/data')
  .then(res => res.json())
  // .then wirft eine Ausnahme, aber kein .catch
  .then(data => data.results.map(r => r.name));

4. API-Ausnahmen

// HTTP-Fehlercodes + Geschäftsfehlercodes
fetch('/api/order')
  .then(res => {
    if (!res.ok) {
      trackError({ type: 'http', status: res.status, url: res.url });
    }
    return res.json();
  });

5. Web Worker / iframe-Fehler

// Interne Worker-Ausnahmen blubbern nicht zum Hauptthread
const worker = new Worker('/worker.js');
worker.onerror = (e) => {
  trackError({
    type: 'worker',
    message: e.message,
    filename: e.filename,
    lineno: e.lineno,
  });
};

Globale Fehlererfassung: Vier Verteidigungslinien

Verteidigungslinie 1: window.onerror

window.onerror = (message, source, lineno, colno, error) => {
  trackError({
    type: 'runtime',
    message,
    source,
    lineno,
    colno,
    stack: error?.stack,
  });
  return false; // Don't suppress default console output
};

Einschränkung: Kann weder Ressourcen-Ladefehler noch Promise-Ausnahmen erfassen.

Verteidigungslinie 2: window.addEventListener('error')

window.addEventListener('error', (event) => {
  if (event.target instanceof HTMLElement) {
    // Ressourcen-Ladefehler
    trackError({
      type: 'resource',
      tagName: event.target.tagName,
      src: event.target.src || event.target.href,
    });
  } else {
    // Laufzeitfehler (kann sich mit onerror duplizieren, Deduplizierung erforderlich)
    trackError({
      type: 'runtime',
      message: event.message,
      stack: event.error?.stack,
    });
  }
}, true); // Capturing-Phase verwenden

Verteidigungslinie 3: window.addEventListener('unhandledrejection')

window.addEventListener('unhandledrejection', (event) => {
  trackError({
    type: 'unhandledRejection',
    reason: event.reason?.message || String(event.reason),
    stack: event.reason?.stack,
  });
});

Verteidigungslinie 4: React Error Boundary

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    trackError({
      type: 'react',
      message: error.message,
      stack: error.stack,
      componentStack: errorInfo.componentStack,
    });
  }

  render() {
    if (this.state.hasError) {
      return <FallbackUI onRetry={() => this.setState({ hasError: false })} />;
    }
    return this.props.children;
  }
}

SourceMap-Deobfuscation: Wiederherstellung echter Stack Traces aus minifiziertem Code

Produktionscode ist minifiziert und obfuskiert, wodurch Fehler-Stack-Traces völlig unlesbar werden. SourceMap-Deobfuscation ist die Kernkompetenz für die Produktionsfehlerbehebung.

Beispiel für einen minifizierten Stack Trace

TypeError: Cannot read properties of undefined (reading 'name')
  at a (main.abc123.js:1:2345)
  at o (main.abc123.js:1:5678)
  at t (main.abc123.js:1:9012)

Deobfuslierter echter Stack Trace

TypeError: Cannot read properties of undefined (reading 'name')
  at getUserInfo (src/services/user.ts:42:15)
  at fetchDashboard (src/pages/dashboard.tsx:128:22)
  at useEffectCallback (src/pages/dashboard.tsx:115:5)

SourceMap-Sicherheitsstrategien

Strategie Sicherheit Komplexität Am besten für
Privates NPM + CI-Deobfuscation Hoch Mittel Die meisten Teams
Serverseitige Deobfuscation mit Sentry Mittel Niedrig Schnelle Integration
Base64 inline SourceMap Niedrig Niedrig Nur Entwicklungsumgebung
Unabhängige .map-Dateien in der Produktion Sehr niedrig Niedrig Nicht empfohlen 
// Deobfuscate using the source-map library
import { SourceMapConsumer } from 'source-map';

async function applySourceMap(position, mapContent) {
  const consumer = await new SourceMapConsumer(mapContent);
  const original = consumer.originalPositionFor({
    line: position.line,
    column: position.column,
  });
  return original;
}

Sentry-Integration in der Praxis

Installation und Initialisierung

npm install @sentry/react @sentry/tracing

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

Sentry.init({
  dsn: 'https://xxx@o123456.ingest.sentry.io/789',
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION,
  tracesSampleRate: 0.1,
  replaysSessionSampleRate: 0.01,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
  beforeSend(event, hint) {
    // Filter meaningless errors
    if (event.exception?.values?.[0]?.type === 'ResizeObserver loop limit exceeded') {
      return null;
    }
    return event;
  },
});

React Router-Integration

const SentryRoutes = Sentry.withSentryReactRouterV6Routing(Routes);

function App() {
  return (
    <SentryRoutes>
      <Route path="/" element={<Home />} />
      <Route path="/dashboard" element={<Dashboard />} />
    </SentryRoutes>
  );
}

Manuelle Meldung und Breadcrumbs

// Manuelle Meldung von Geschäftsausnahmen
Sentry.captureException(new Error('Order payment timeout'), {
  tags: { orderId: 'ORD-12345', paymentMethod: 'alipay' },
  extra: { retryCount: 3, lastAttempt: Date.now() },
});

// Breadcrumbs hinzufügen (Benutzerverhaltensspur)
Sentry.addBreadcrumb({
  category: 'ui.click',
  message: 'Clicked submit button',
  level: 'info',
});

Aufbau eines leichtgewichtigen Monitoringsystems

Wenn Sie nicht von Drittanbieterdiensten abhängig sein möchten, können Sie Ihr eigenes System aufbauen:

Datensammlungs-SDK

class ErrorMonitor {
  constructor(options) {
    this.endpoint = options.endpoint;
    this.queue = [];
    this.timer = null;
    this.install();
  }

  install() {
    window.addEventListener('error', this.handleError.bind(this), true);
    window.addEventListener('unhandledrejection', this.handleRejection.bind(this));
  }

  handleError(event) {
    this.report({
      type: event.target instanceof HTMLElement ? 'resource' : 'runtime',
      message: event.message || event.target?.outerHTML,
      stack: event.error?.stack,
      timestamp: Date.now(),
      url: location.href,
      ua: navigator.userAgent,
    });
  }

  handleRejection(event) {
    this.report({
      type: 'unhandledRejection',
      message: event.reason?.message || String(event.reason),
      stack: event.reason?.stack,
      timestamp: Date.now(),
    });
  }

  report(data) {
    this.queue.push(data);
    if (!this.timer) {
      this.timer = setTimeout(() => this.flush(), 5000);
    }
  }

  flush() {
    if (this.queue.length === 0) return;
    const batch = this.queue.splice(0);
    navigator.sendBeacon(this.endpoint, JSON.stringify(batch));
    this.timer = null;
  }
}

Kennzahlen-Dashboard

Kennzahl Berechnung Alarm-Schwellenwert
JS-Fehlerrate Fehler-PV / Gesamt-PV > 0.1%
API-Fehlerrate 5xx-Anzahl / Gesamtanfragen > 1%
Erstbildschirm-Absturzrate Leerer-Bildschirm-PV / Gesamt-PV > 0.01%
Mittlere Reparaturzeit Zeit vom ersten Alarm bis zum Deployment > 30min

Checkliste der Best Practices

  1. Volle Abdeckung mit vier Verteidigungslinien: onerror + error-Ereignis + unhandledrejection + Error Boundary
  2. Kein SourceMap in der Produktion: Getrennte Build-Artefakte, Deobfuscation in der CI-Umgebung
  3. Fehler-Sampling und Filterung: Verhindern, dass hochfrequente bedeutungslose Fehler echte Probleme überlagern
  4. Benutzerverhaltenswiederholung: Breadcrumbs + Session Replay zur Beschleunigung der Lokalisierung
  5. Alarmstufung: P0 sofortige Benachrichtigung, P1 Ticket-Verfolgung, P2 Wochenbericht-Zusammenfassung
  6. Versionszuordnung: Jedes Release trägt eine Versionsnummer, Fehler werden automatisch mit Codeänderungen verknüpft
  7. Datenschutzkonformität: Gemeldete Daten bereinigen, keine persönlichen Benutzerdaten einschließen
  8. Leistungskorrelation: Fehlermonitoring mit Leistungsmonitoring verknüpfen, um Ursachen von Leistungsverschlechterung zu entdecken

Probiere diese browser-lokalen Tools aus — keine Registrierung erforderlich →

#错误监控#Sentry#SourceMap#异常捕获#DevOps