Corriger les erreurs d'analyse JSON : vérifier Unexpected token pas à pas

L'essentiel : en cas d'erreur de parsing, lisez la ligne et la colonne rapportées pour trouver le premier caractère illégal, puis décidez s'il s'agit d'un guillemet manquant, d'une virgule manquante, d'une virgule finale, d'un BOM ou d'une troncature — ne relisez pas tout le document depuis le début.

Un message d'erreur ne vous dit jamais « ce qui est faux » ; il vous dit seulement « où le parseur ne pouvait plus continuer ». Ces deux positions ne sont souvent pas le même endroit.

1. D'abord, traduire l'erreur en coordonnées

Le même JSON cassé produit des erreurs complètement différentes selon les langages, mais toutes peuvent être converties en « quelle ligne, quel caractère » :

Une fois la position en main, collez le JSON dans le parseur JSON en ligne ; l'outil place le curseur à l'emplacement de l'erreur et met en évidence le numéro de ligne et de colonne — cette étape économise 90 % du scrutage de caractères.

2. Six erreurs à haute fréquence

1. Virgule finale

复制{
  "name": "json",
  "version": 1,
}

Il y a une virgule en trop avant }. La spécification JSON n'autorise pas les virgules finales, tandis que les littéraux d'objet JavaScript les autorisent, donc une configuration copiée depuis du code est la plus susceptible d'en porter une. Correction : supprimez la dernière virgule ; si ces données vivent de toute façon dans un fichier JS, passez à la conversion JSON5 au lieu de les forcer en JSON.

2. Guillemets simples et clés sans guillemets

复制{ 'name': 'json' }
{ name: "json" }

Les chaînes JSON ne peuvent utiliser que des guillemets doubles, et les clés doivent aussi être des chaînes entre guillemets doubles. Ces deux formes sont la syntaxe assouplie de JSON5 / JavaScript, pas de JSON. Un guillemet double à l'intérieur d'une chaîne doit s'écrire \", et une barre oblique inverse \\.

3. Commentaires

复制{
  // Timeout in milliseconds
  "timeout": 3000
}

La grammaire de la RFC 8259 n'a aucune place pour les commentaires. Soit vous supprimez les commentaires, soit vous enregistrez en .jsonc / .json5 et utilisez un parseur qui les prend en charge. Pour les compromis entre les différentes « solutions de commentaires », voir Comment écrire des commentaires en JSON.

4. Retours à la ligne bruts et caractères de contrôle dans les chaînes

复制{"sql": "SELECT *
FROM t"}

Les chaînes JSON ne peuvent pas contenir de retours à la ligne bruts, de tabulations ni les caractères de contrôle U+0000–U+001F ; il faut les écrire \n, \t, \u0009. Quand il faut fourrer du texte multi-ligne dans JSON, échappez-le d'abord dans un éditeur, ou traitez-le uniformément avec la minification et l'échappement JSON.

5. En-tête BOM

L'UTF-8 enregistré par le Bloc-notes Windows porte les trois octets EF BB BF. JSON.parse rapporte Unexpected token en rencontrant un BOM, et l'œil ne peut pas du tout le voir. Comment le savoir : inspectez l'en-tête du fichier en hexadécimal, ou copiez le contenu dans un outil en ligne et voyez si le premier caractère s'affiche comme . Correction : enregistrez en « UTF-8 sans BOM ».

6. Contenu tronqué

Un journal qui n'a imprimé que les 4096 premiers caractères, une réponse d'API coupée par une passerelle, un téléchargement interrompu — le signe distinctif de cette classe est « l'erreur est à la fin » et les comptes de crochets ne correspondent pas. Comptez d'abord les crochets : si les fermetures de { et [ ne correspondent pas, c'est une troncature, pas une erreur de syntaxe. Dans ce cas ne corrigez rien — allez récupérer les données complètes.

3. Deux fausses alertes liées au chinois et à l'échappement

Le chinois devient \u4e2d\u6587 : c'est de l'échappement JSON valide, pas du texte brouillé. Après parsing, la valeur est restaurée en chinois ; la forme \u n'apparaît que si vous regardez directement la chaîne brute. Quand il faut la montrer à des gens, affichez-la simplement avec l'outil de formatage ; vous n'avez à vous soucier de la stratégie d'échappement que lorsque le chinois doit survivre dans une URL ou un journal.

Le chinois devient du texte brouillé comme 涓枃 : c'est un problème d'encodage, pas un problème JSON. Cela se produit quand des octets UTF-8 sont décodés en GBK, produisant ce motif régulier de « trois caractères pour un seul caractère chinois ». Vérifiez le Content-Type: application/json; charset=utf-8 de l'en-tête de réponse, et vérifiez si encoding='utf-8' est explicitement spécifié à la lecture du fichier.

4. Un workflow de réparation en cinq minutes

1. Collez-le dans l'outil : utilisez d'abord le parseur en ligne pour localiser la première erreur, et ne corrigez qu'une chose à la fois ;
2. Validez après chaque correction : reparsez après chaque changement, pour que corriger plusieurs endroits d'un coup ne laisse de nouvelles erreurs masquer l'ancienne ;
3. Minifiez une fois : retirez les espaces avec Minify et reparsez ; cela distingue les « erreurs structurelles » des « problèmes d'espaces ou de retours à la ligne » ;
4. Comparez les structures : si une erreur apparaît soudainement après un changement, utilisez le diff JSON contre la version précédente ; la différence est généralement une virgule ;
5. Validation au niveau des champs : si la syntaxe passe mais que la couche métier rejette (champ manquant, type faux), cela relève de la validation JSON Schema, pas d'un problème de syntaxe.

5. Pourquoi l'un de deux extraits JSON « identiques » parse et l'autre non

La cause la plus courante est les caractères invisibles : la virgule pleine largeur ，, les guillemets pleine largeur “”, l'espace insécable U+00A0, l'espace de largeur nulle U+200B. À l'écran ils sont presque indiscernables de leurs équivalents demi-largeur, mais aucun ne fait partie de la grammaire JSON.

Il n'y a qu'une façon de le savoir : copiez le contenu autour du caractère fautif et inspectez les points de code octet par octet. Exécuter ce qui suit dans une console de navigateur liste chaque caractère non-ASCII et hors des plages chinoises :

复制[...text].filter((ch) => {
  const code = ch.codePointAt(0);
  return code > 127 && !(code >= 0x4e00 && code <= 0x9fff);
});

Si 0x201c (guillemet double gauche), 0xff0c (virgule pleine largeur) ou 0x00a0 apparaît dans la sortie, ce sont les coupables.

6. Prévenir coûte moins cher que réparer

• Lancez une vérification de parsing sur les fichiers de configuration avant de committer ; une ligne en CI suffit : node -e "JSON.parse(require('fs').readFileSync('config.json','utf8'))" ;
• Générez les réponses d'API avec une bibliothèque de sérialisation ; ne concaténez jamais des chaînes à la main — les chaînes construites à la main sont la seule source de virgules finales et de guillemets manquants ;
• Lors de la journalisation de JSON, appelez d'abord JSON.stringify au lieu de l'interpoler dans un gabarit, pour qu'une charge utile à moitié écrite ne soit pas prise pour un message complet.

FAQ

Comment localiser rapidement la position d'une erreur de syntaxe JSON ?

Prenez la position ou la ligne/colonne rapportée par le parseur ; position est un décalage de caractère base 0, pas un numéro de ligne, tandis que Java Jackson et Python rapportent directement ligne et colonne. Collez le JSON dans le parseur JSON en ligne et l'outil place le curseur à l'emplacement de l'erreur et met en évidence ligne et colonne. Si l'erreur se situe au début, vérifiez l'en-tête du fichier pour un BOM et cherchez des caractères invisibles.

Pourquoi une configuration copiée depuis du code porte-t-elle si souvent une virgule finale ?

La spécification JSON interdit les virgules finales tandis que les littéraux d'objet JavaScript les autorisent, donc une configuration copiée depuis du code JS en porte facilement une. La correction consiste simplement à supprimer la dernière virgule ; si les données appartiennent de toute façon à un fichier JS, passer à la conversion JSON5 convient mieux que de les forcer en JSON.

Puis-je parser un fichier de configuration contenant des commentaires comme du JSON normal ?

Non — la grammaire de la RFC 8259 n'a aucune place pour les commentaires, donc le parser directement lève une erreur. Soit vous supprimez les commentaires, soit vous enregistrez en .jsonc / .json5 et utilisez un parseur qui prend en charge les commentaires. Pour les compromis entre solutions de commentaires, voir Comment écrire des commentaires en JSON.