Quand une erreur JavaScript survient en production, la stack trace pointe dans votre bundle minifié (main.a8f42b.js:1:42819). Inutile pour déboguer. Les source maps sont les fichiers JSON émis par votre bundler qui nous indiquent comment retraduire ces numéros de ligne/colonne vers votre source d'origine.
Le suivi des erreurs — et les source maps avec lui — est disponible sur les plans Pro et supérieurs.
Comment les source maps fonctionnent dans Zenovay
- Votre build produit un bundle (par ex.
main.a8f42b.js) et une source map correspondante (main.a8f42b.js.map). - Vous uploadez la source map vers Zenovay via l'API de suivi des erreurs.
- Quand une erreur arrive, le tracker la fait correspondre à vos maps uploadées en utilisant le fichier bundle et le
releaseque vous avez uploadé. - Le dashboard affiche le fichier d'origine, la ligne, la colonne et un extrait de code.
Les source maps sont stockées contre un identifiant de release — soit un SHA Git, un tag semver, ou n'importe quelle chaîne que vous définissez. Si le release de l'erreur ne correspond pas à une map uploadée, vous verrez la ligne minifiée dans le dashboard.
Uploader des source maps
Les source maps sont uploadées via l'API de suivi des erreurs. L'endpoint accepte un body JSON :
POST https://api.zenovay.com/api/errors/{websiteId}/sourcemap
| Champ | Requis | Description |
|---|---|---|
fileName | oui | Le nom sous lequel la map doit être stockée (p. ex. main.js) |
fileUrl | oui | L'URL publique du bundle auquel la map appartient |
release | recommandé | L'identifiant de release auquel cette map s'applique (omettez pour stocker sous default) |
mapContent | recommandé | Le contenu du fichier .map |
mapUrl | optionnel | Une URL à partir de laquelle la map peut être récupérée, au lieu d'intégrer mapContent |
Ces endpoints nécessitent une session Zenovay authentifiée — passez votre token d'accès au tableau de bord en tant que token Bearer (le token courte durée que votre navigateur utilise quand vous êtes connecté à app.zenovay.com). Ils ne sont pas accessibles avec une clé API REST zv_*.
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
Pour voir ce qui a déjà été uploadé pour un site, listez vos maps :
GET https://api.zenovay.com/api/errors/{websiteId}/sourcemaps — ajoutez ?release=v2.4.1 pour filtrer sur une version.
Exécutez l'upload immédiatement après chaque build de production pour que chaque version soit livrée avec les maps, et vérifiez le statut de la réponse pour qu'un upload échoué soit détecté plutôt que silencieusement ignoré. Notez que le token d'accès a une courte durée de vie, il doit donc être actualisé à chaque upload — un token de session capturé du dashboard ne restera valide que peu de temps.
À propos de l'identifiant de release
Le champ release est le lien entre une erreur capturée et une map uploadée. Les erreurs sont stockées avec la valeur release sous laquelle elles ont été signalées, et une map est associée à une erreur quand les deux partagent le même release.
Si vous voulez que les erreurs soient tagées avec une version dans le dashboard, votre application doit signaler cette version à chaque erreur qu'elle envoie. Uploadez les maps sous le même identifiant, et les deux sont alignées.
Vérifier que ça marche
- Uploadez une map, puis déclenchez une erreur connue en production.
- Ouvrez le dashboard de votre site, allez à l'onglet Errors et ouvrez l'erreur.
- La section stack-trace doit afficher votre chemin de fichier d'origine (par ex.
src/components/Checkout.tsx:42) et une courte aperçu de code.
Si elle affiche toujours la ligne minifiée, vérifiez :
- Le release sous lequel l'erreur a été signalée correspond au release sous lequel vous avez uploadé la map.
- La
fileUrluploadée correspond au bundle d'où provient l'erreur. - Le fichier
.mapn'est pas tronqué (un upload partiel peut laisser une map inutilisable).
Confidentialité
Les source maps contiennent l'intégralité de votre code d'origine. Elles sont stockées en privé, restreintes à votre site et ne sont jamais servies publiquement.