Wenn ein JavaScript-Fehler in Produktion auftritt, zeigt der Stack-Trace in Ihr minifiziertes Bundle (main.a8f42b.js:1:42819). Das ist zum Debuggen nutzlos. Source Maps sind die JSON-Dateien, die Ihr Bundler ausgibt und die uns sagen, wie wir diese Zeilen-/Spaltennummern zurück in Ihren Originalquellcode übersetzen.
Error-Tracking — und Source Maps damit — ist auf Pro-Plans und höher verfügbar.
Wie Source Maps in Zenovay funktionieren
- Ihr Build erzeugt ein Bundle (z. B.
main.a8f42b.js) und eine entsprechende Source Map (main.a8f42b.js.map). - Sie laden die Source Map zu Zenovay hoch — über die Error-Tracking-API.
- Wenn ein Fehler eintrifft, gleicht der Tracker ihn gegen Ihre hochgeladenen Maps ab, indem er die Bundle-Datei und den
releaseverwendet, den Sie hochgeladen haben. - Das Dashboard zeigt die Originaldatei, Zeile, Spalte und einen Code-Snippet.
Source Maps werden gegen einen Release-Identifier gespeichert — entweder ein Git-SHA, ein Semver-Tag oder ein beliebiger String, den Sie setzen. Stimmt der Release eines ankommenden Fehlers nicht mit einer hochgeladenen Map überein, sehen Sie die minifizierte Zeile im Dashboard.
Source Maps hochladen
Source Maps werden über die Error-Tracking-API hochgeladen. Der Endpoint akzeptiert einen JSON-Body:
POST https://api.zenovay.com/api/errors/{websiteId}/sourcemap
| Feld | Erforderlich | Beschreibung |
|---|---|---|
fileName | ja | Der Name, unter dem die Map gespeichert wird (z. B. main.js) |
fileUrl | ja | Die öffentliche URL des Bundles, zu dem die Map gehört |
release | empfohlen | Der Release-Identifier, auf den diese Map zutrifft (weglassen = unter default gespeichert) |
mapContent | empfohlen | Der Inhalt der .map-Datei |
mapUrl | optional | Eine URL, von der die Map abgerufen werden kann, anstatt mapContent einzufügen |
Diese Endpoints erfordern eine authentifizierte Zenovay-Sitzung — übergeben Sie Ihr Dashboard-Zugrifftoken als Bearer-Token (das kurzlebige Token, das Ihr Browser verwendet, wenn Sie in app.zenovay.com angemeldet sind). Sie sind nicht mit einem zv_* REST-API-Schlüssel erreichbar.
curl -X POST "https://api.zenovay.com/api/errors/{websiteId}/sourcemap" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'JSON'
{
"fileName": "main.js",
"fileUrl": "https://example.com/static/main.js",
"release": "v2.4.1",
"mapContent": "<contents of main.js.map>"
}
JSON
Um zu sehen, was bereits für eine Website hochgeladen wurde, listen Sie Ihre Maps auf:
GET https://api.zenovay.com/api/errors/{websiteId}/sourcemaps — fügen Sie ?release=v2.4.1 hinzu, um auf eine bestimmte Version zu filtern.
Führen Sie den Upload direkt nach jedem Produktions-Build durch, damit jedes Release mit Maps ausgeliefert wird, und überprüfen Sie den Response-Status, damit ein fehlgeschlagener Upload abgefangen statt stillschweigend übersprungen wird. Beachten Sie, dass das Zugrifftoken kurzlebig ist, daher muss es bei jedem Upload aktualisiert werden — ein von der Benutzeroberfläche erfasstes Session-Token bleibt nicht lange gültig.
Über den Release-Identifier
Das Feld release ist die Verbindung zwischen einem erfassten Fehler und einer hochgeladenen Map. Fehler werden mit dem release-Wert gespeichert, unter dem sie gemeldet wurden, und eine Map wird zu einem Fehler abgeglichen, wenn beide denselben Release teilen.
Wenn Sie Fehler mit einem Release im Dashboard gekennzeichnet haben möchten, muss Ihre Anwendung diesen Release mit jedem Fehler melden, den sie sendet. Laden Sie Maps unter demselben Identifier hoch, und die beiden stimmen überein.
Verifizieren, dass es funktioniert
- Map hochladen, dann einen bekannten Fehler in Produktion auslösen.
- Zum Dashboard Ihrer Website gehen, die Registerkarte Errors öffnen und den Fehler öffnen.
- Der Stack-Trace-Bereich sollte Ihren ursprünglichen Dateipfad (z. B.
src/components/Checkout.tsx:42) und eine kurze Code-Vorschau zeigen.
Zeigt es immer noch die minifizierte Zeile, prüfen Sie:
- Der Release, unter dem der Fehler gemeldet wurde, stimmt mit dem Release überein, unter dem Sie die Map hochgeladen haben.
- Die
fileUrl, die Sie hochgeladen haben, stimmt mit dem Bundle überein, aus dem der Fehler stammt. - Die
.map-Datei ist nicht abgeschnitten (ein Teil-Upload kann zu einer unbenutzbar gemachten Map führen).
Datenschutz
Source Maps enthalten Ihren vollständigen Originalcode. Sie werden privat gespeichert, auf Ihre Website beschränkt und niemals öffentlich ausgeliefert.