Vyhledávání chybových zpráv JSON: od textu chyby přímo k opravě

Stručně: když se objeví chyba JSON.parse, nejprve si vezměte pozici a token; pozice 0 znamená kontrolu HTML odpovědi, BOM nebo špatného typu a zpráva „Expected“ znamená pohled na předchozí znak – nečtěte znovu řádek po řádku od hlášené pozice.

Text chyby není šum – je to odpověď. Parser vám říká, na který znak narazil, co očekával a co skutečně dostal. Hledání podle chybové zprávy je lepší než ruční přepisování celého dokumentu.

Každá chyba JSON.parse() má tři části: pozici (offset znaku nebo řádek a sloupec), očekávání (Expected...) a skutečnost (Unexpected token X nebo xxx is not valid JSON). Enginy je formulují různě – Chrome a Node (V8) říkají Expected ',' or '}' after property value in JSON at position 25, Firefox říká JSON.parse: expected ',' or '}' after property value in object at line 3 column 1, Safari říká JSON Parse error: Expected ',' or '}' – ale všechny tři ukazují na stejné syntaktické rozbití. Když chybu vyhledáváte, ignorujte formulaci a vezměte tři fakta: který znak, co se očekávalo, co dorazilo.

1. Vyhledávací tabulka 12 chyb

Levý sloupec je nejlépe identifikovatelný fragment z vaší konzole (znění V8). Varianty Firefoxu a Safari jsou v závorkách.

První dvě si zaslouží bližší pohled, protože ani jedna neznamená „vaše JSON je špatně“ – znamenají „to, co jste dostali, není to, co si myslíte“.

2. Tři časté zdroje chyby na pozici 0

Pozice 0 znamená, že neplatný je úplně první znak. Pokud nic podezřelého nevidíte, je znak pravděpodobně neviditelný. Tři obvyklí podezřelí:

První: <, tedy HTML. Jde o nejčastější chybu parsování v produkci. Špatná URL, relace, kterou brána přesměrovala kvůli vypršení, nebo šablona chyby serveru – tělo začíná <!DOCTYPE html> a parser skončí na prvním znaku. Správný krok je otevřít panel Network, přečíst surovou odpověď a opravit volání API, nikoli JSON.

Druhý: BOM nebo znaky s nulovou šířkou. Soubory uložené Poznámkovým blokem ve Windows často začínají UTF-8 BOM (\uFEFF) a text zkopírovaný z webových stránek nebo chatů může nést mezery s nulovou šířkou (\u200B–\u200D). Pro vás neviditelné, pro parser zjevné:

复制// Před parsováním odstraňte BOM a znaky s nulovou šířkou
const cleaned = raw.replace(/^\uFEFF/, '').replace(/[\u200B-\u200D]/g, '');
const data = JSON.parse(cleaned);

Třetí: špatný typ. JSON.parse(undefined) hlásí "undefined" is not valid JSON; JSON.parse(someObject) hlásí Unexpected token o (objekt byl převeden na "[object Object]" a o je na pozici 1 neplatné). Obě znamenají „data už jsou parsovaná“ nebo „žádná data nikdy nebyla“. Kontrolujte typ, ne syntaxi:

复制let data = text;
if (typeof data === 'string') {
  data = JSON.parse(data); // Parsujte jen tehdy, když jde skutečně o řetězec
}

3. Pozice ukazuje níž; příčina je výš

Dvě chyby vás matou ohledně umístění a jsou to dvě nejčastěji chybně čtené položky tabulky:

• Chybějící čárka: {"a": 1 "b": 2} hlásí Expected ',' or '}' after property value na řádku s "b". Hlášení je správné, ale oprava patří na konec předchozího řádku.
• Chybějící uzavírací závorka: v hlubokém vnoření chybí jeden } nebo ], parser spolkne vše do konce vstupu a ohlásí Unexpected end of JSON input. Pozice je konec souboru; skutečná mezera může být mnohem dřív. Hledejte zpětně poslední neuzavřenou { nebo [ – počítání párů je lepší než zrak.

Obecná technika je bisekce: odřízněte text před hlášenou pozicí a parsujte ho samostatně. Pokud projde, problém je blízko hlášené pozice; pokud ne, bisekujte dál. Hranice prvního selhávajícího bloku je skutečné místo chyby. U velkých souborů dokument nejprve naformátujte – se zarovnaným odsazením je chybějící úroveň vidět na první pohled (online formátovač JSON k tomu poslouží).

4. Čtyři „falešně zdravé“ stavy, které projdou, ale chovají se špatně

Horší než chyba je žádná chyba a špatná data. Ve všech čtyřech případech je JSON platný a parser je spokojený – problém je tvar dat:

1. Dvojí kódování: celý dokument byl dvakrát prohnán JSON.stringify, takže parsování vrátí řetězec, nikoli objekt. Pokud je typeof result === 'string', parsujte znovu – ale najděte a opravte dvojí serializaci u zdroje.
2. Duplicitní klíče tiše přepisují: {"name": "Tom", "name": "Jerry"} je platný JSON, většina parserů si nestěžuje a vyhraje druhá hodnota. Kousne to při slučování dat z několika zdrojů; odhalte to přísným validátorem JSON, dokud to nekousne.
3. NDJSON zpracovaný jako jeden dokument: streamovací API vydávají jeden objekt na řádek; parsování celého textu selže s Unexpected non-whitespace character after JSON. Rozdělte podle \n a parsujte po řádcích.
4. Tichá ztráta přesnosti čísel: celá čísla nad 2^53 - 1 (snowflake ID) se vracejí s vynulovanými posledními číslicemi a bez jakékoli chyby. ID přenášejte jako řetězce.

Společný motiv: parser si myslí, že je vše v pořádku. Když tedy data z API vypadají špatně, nejprve vypište prvních 80 znaků surového textu a jeho typeof – potvrďte tvar, než začnete řešit obsah.

5. Udělejte chyby nemožnými už při psaní

Vyhledávací tabulka je nástroj po faktu; prevence je nástroj před faktem. Čtyři návyky zachytí většinu chyb dřív, než vzniknou:

复制// 1. Dvě kontroly před parsováním jakékoli odpovědi
const response = await fetch('/api/users');
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: API nevrátilo data`);
}
const contentType = response.headers.get('content-type') ?? '';
if (!contentType.includes('application/json')) {
  throw new Error(`Očekáván JSON, dorazilo ${contentType}`);
}
const data = await response.json(); // 2. json() už parsuje – neparsujte znovu

• Generujte serializací, nikdy neskládejte: JSON.stringify() správně ošetřuje uvozovky, zalomení řádků i řídicí znaky; ručně sestavené řetězce jsou hlavním zdrojem Bad control character a Unterminated string.
• Vždy zachytávejte: vyhozená chyba JSON.parse je synchronní pád, pokud ji něco nezachytí. U nedůvěryhodného vstupu – localStorage, externí soubory – potřebuje blok catch výchozí hodnotu nebo explicitní hlášení chyby.
• Strukturu předejte schématu: platná syntaxe neznamená platnou strukturu. Chybějící pole a špatné typy patří k validaci JSON Schema na hranici; viz co JSON Schema řeší.

6. Rychlá rozhodovací cesta

Zhuste celý článek do jednoho rozhodovacího pořadí. Když uvidíte chybu, nejprve si vezměte pozici a token:

1. Pozice 0 → zkontrolujte tři zdroje: < (HTML), BOM, špatný typ;
2. end of input → zkontrolujte prázdné nebo zkrácené tělo a poté hledejte zpětně neuzavřené závorky;
3. Expected ... → podívejte se na předchozí znak; obvykle chybí čárka nebo uvozovka;
4. after JSON data → bylo spojeno více dokumentů; rozdělte po řádcích;
5. Projde, ale data vypadají špatně → projděte čtyři kontroly „falešného zdraví“.

V kombinaci s postupnou triáží v článku jak opravit chyby parsování JSON se 90 % problémů s parsováním vyřeší do pěti minut. Uložte si samotný text chyby do záložek – je to ladicí log, který za vás napsal parser, jeho znění se mění jednou za tři roky a jedno vyhledání se vyplatí na rok.

Co znamená „Unexpected token in JSON“?

Parser narazil na znak, který je na daném místě gramatiky JSON neplatný. Token je odmítnutý znak: < obvykle znamená, že API vrátilo HTML, ' znamená jednoduché uvozovky, / znamená komentář a obyčejné písmeno obvykle znamená klíč bez uvozovek nebo literál existující jen v JavaScriptu, jako undefined nebo NaN. Přečtěte nejprve token, poté pozici a příčina se zúží na jednu.

Jak opravit „Unexpected end of JSON input“?

Dva zdroje: prázdný vstup (prázdné tělo odpovědi nebo prázdný řetězec v localStorage) nebo zkrácený vstup (přerušené stahování, kopie bez posledního řádku, limit velikosti). Prázdný případ ošetřete pomocí if (!text) return; poté ověřte úplnost a uzavřete poslední neuzavřenou {, [ nebo ". Pozor, chyba může pocházet i z hluboko chybějící závorky – pozice prostě náhodou vyšla na konec souboru.

Proč Chrome, Firefox a Safari hlásí chyby různě?

Tyto tři prohlížeče používají různé JS enginy (V8, SpiderMonkey, JavaScriptCore) a každý formuluje chyby po svém; MDN dokumentuje všechny oficiální varianty. Všechny tři však nesou stejné tři prvky – pozici, očekávání, skutečnost – se vzájemně jednoznačnou sémantikou. Přeložte je do znění V8 a použijte tuto tabulku tak, jak je.

Pozice chyby ukazuje na místo, které vypadá dobře – co teď?

Skutečná chyba je dřív. Typické případy: chybějící čárka (hlášená na následujícím řádku) a chybějící uzavírací závorka (hlášená na konci souboru). Projděte zpětně od hlášené pozice token po tokenu, nebo použijte bisekci: parsujte první polovinu samostatně a hranice prvního selhávajícího bloku je skutečné místo chyby.