Come correggere gli errori di parsing JSON: controllo passo passo di Unexpected token

In sintesi: quando si verifica un errore di parsing, leggi la riga e la colonna riportate per trovare il primo carattere illegale, poi decidi se si tratta di una virgoletta mancante, una virgola mancante, una virgola finale, un BOM o un troncamento — non rileggere tutto il documento dall'inizio.

Un messaggio di errore non ti dice mai "cosa è sbagliato"; ti dice solo "dove il parser non è più riuscito a procedere". Spesso queste due posizioni non coincidono.

1. Prima traduci l'errore in coordinate

Lo stesso JSON rotto produce errori completamente diversi in linguaggi diversi, ma tutti possono essere convertiti in "quale riga, quale carattere":

Una volta ottenuta la posizione, incolla il JSON nel parser JSON online; lo strumento colloca il cursore nella posizione dell'errore ed evidenzia riga e colonna — questo passaggio risparmia il 90% dell'ispezione a occhio dei caratteri.

2. Sei errori ad alta frequenza

1. Virgola finale

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

C'è una virgola in più prima di }. La specifica JSON non ammette virgole finali, mentre i letterali oggetto di JavaScript sì, quindi le configurazioni copiate dal codice sono le più propense a portarne una. Correzione: elimina l'ultima virgola; se questi dati vivono già in un file JS, passa alla conversione JSON5 invece di forzarli in JSON.

2. Apici singoli e chiavi senza virgolette

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

Le stringhe JSON possono usare solo virgolette doppie, e anche le chiavi devono essere stringhe tra virgolette doppie. Queste due forme sono la sintassi rilassata di JSON5 / JavaScript, non di JSON. Una virgoletta doppia dentro una stringa deve essere scritta come \", e una barra rovesciata come \\.

3. Commenti

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

La grammatica di RFC 8259 non prevede i commenti. Elimina i commenti, oppure salva come .jsonc / .json5 e usa un parser che supporta i commenti. Per i compromessi tra i vari "schemi di commento", vedi Come scrivere commenti in JSON.

4. A capo grezzi e caratteri di controllo dentro le stringhe

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

Le stringhe JSON non possono contenere line feed, tab o caratteri di controllo U+0000–U+001F grezzi; devono essere scritti come \n, \t, \u0009. Quando devi inserire testo multiriga in JSON, applica prima l'escape in un editor, oppure gestiscilo in modo uniforme con Minify ed escape JSON.

5. Header BOM

L'UTF-8 salvato dal Blocco note di Windows porta i tre byte EF BB BF. JSON.parse riporta Unexpected token quando incontra un BOM, e l'occhio non riesce assolutamente a vederlo. Come accorgersene: ispeziona l'header del file in esadecimale, oppure copia il contenuto in uno strumento online e osserva se il primo carattere appare come . Correzione: salva come "UTF-8 senza BOM".

6. Contenuto troncato

Un log che ha stampato solo i primi 4096 caratteri, una risposta API tagliata da un gateway, un download interrotto — il tratto distintivo di questa classe è "l'errore è alla fine" e i conteggi delle parentesi non tornano. Conta prima le parentesi: se le chiusure di { e [ non corrispondono, è un troncamento, non un errore di sintassi. In quel caso non correggere nulla — vai a prendere i dati completi.

3. Due falsi allarmi che coinvolgono testo cinese ed escape

Il cinese diventa \u4e2d\u6587: è un escape JSON valido, non testo illeggibile. Dopo il parsing il valore viene ripristinato in cinese; la forma \u compare solo guardando direttamente la stringa grezza. Quando devi mostrarlo alle persone, basta produrlo con lo strumento di formattazione; devi preoccuparti della strategia di escape solo quando il cinese deve sopravvivere in un URL o in un log.

Il cinese diventa testo illeggibile come 涓枃: è un problema di codifica, non di JSON. Accade quando i byte UTF-8 vengono decodificati come GBK, producendo questo schema regolare di "tre caratteri al posto di un carattere cinese". Controlla Content-Type: application/json; charset=utf-8 nell'header della risposta e verifica che encoding='utf-8' sia specificato esplicitamente durante la lettura del file.

4. Un flusso di riparazione in cinque minuti

1. Incollalo nello strumento: usa prima il parser online per individuare il primo errore, e correggi un errore alla volta;
2. Valida dopo ogni correzione: ripeti il parsing dopo ogni modifica, così correggere più punti contemporaneamente non lascia che i nuovi errori mascherino quello vecchio;
3. Esegui un minify: rimuovi gli spazi con Minify e ripeti il parsing; questo distingue gli "errori strutturali" dai "problemi di spaziatura o di a capo";
4. Confronta la struttura: se un errore compare improvvisamente dopo una modifica, usa JSON diff rispetto alla versione precedente; la differenza è di solito quella virgola;
5. Validazione a livello di campo: se la sintassi passa ma il livello applicativo la rifiuta (campo mancante, tipo errato), rientra nella validazione JSON Schema, non è un problema di sintassi.

5. Perché uno di due JSON "apparentemente identici" viene analizzato e l'altro no

La causa più comune sono i caratteri invisibili: la virgola a larghezza piena ，, le virgolette a larghezza piena “”, lo spazio unificatore U+00A0, lo spazio a larghezza zero U+200B. Sullo schermo sono quasi indistinguibili dalle controparti a mezza larghezza, ma nessuno di essi fa parte della grammatica JSON.

C'è un solo modo per scoprirlo: copia il contenuto intorno al carattere problematico e ispeziona i code point byte per byte. Eseguendo quanto segue nella console del browser ottieni l'elenco di ogni carattere non ASCII e fuori dagli intervalli cinesi:

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

Se nell'output compaiono 0x201c (virgoletta doppia sinistra), 0xff0c (virgola a larghezza piena) o 0x00a0, sono i colpevoli.

6. Prevenire costa meno che riparare

• Esegui un controllo di parsing sui file di configurazione prima del commit; in CI basta una riga: node -e "JSON.parse(require('fs').readFileSync('config.json','utf8'))";
• Genera le risposte API con una libreria di serializzazione; non concatenare mai stringhe a mano — le stringhe costruite a mano sono l'unica fonte di virgole finali e virgolette mancanti;
• Quando registri JSON nei log, chiama prima JSON.stringify invece di interpolarlo in un template, così un payload scritto a metà non viene scambiato per un messaggio completo.

FAQ

Come posso individuare rapidamente la posizione di un errore di sintassi JSON?

Prendi la position o la riga/colonna riportata dal parser; position è un offset di carattere a base 0, non un numero di riga, mentre Java Jackson e Python riportano direttamente riga e colonna. Incolla il JSON nel parser JSON online e lo strumento colloca il cursore nella posizione dell'errore ed evidenzia riga e colonna. Se l'errore è all'inizio, controlla nell'header del file la presenza di un BOM e cerca caratteri invisibili.

Perché una configurazione copiata dal codice è così propensa a portare una virgola finale?

La specifica JSON vieta le virgole finali mentre i letterali oggetto di JavaScript le consentono, quindi le configurazioni copiate dal codice JS ne ereditano facilmente una. La correzione consiste semplicemente nell'eliminare l'ultima virgola; se i dati appartengono comunque a un file JS, passare alla conversione JSON5 è più adatto che forzarli in JSON.

Posso analizzare come JSON normale un file di configurazione che contiene commenti?

No — la grammatica di RFC 8259 non prevede i commenti, quindi il parsing diretto genera un errore. Elimina i commenti, oppure salva come .jsonc / .json5 e usa un parser che supporta i commenti. Per i compromessi tra gli schemi di commento, vedi Come scrivere commenti in JSON.