Como corrigir erros de análise JSON: verificando Unexpected token passo a passo

Resumo da ópera: diante de um erro de análise, leia a linha e a coluna informadas para encontrar o primeiro caractere ilegal e então decida se é falta de aspas, falta de vírgula, vírgula final, BOM ou truncamento — não releia o documento inteiro desde o começo.

Uma mensagem de erro nunca diz "o que está errado"; ela só diz "onde o analisador não conseguiu mais avançar". Essas duas posições frequentemente não são o mesmo lugar.

1. Primeiro, traduza o erro em coordenadas

O mesmo JSON quebrado gera erros completamente diferentes em linguagens diferentes, mas todos podem ser convertidos em "qual linha, qual caractere":

Depois de ter a posição, cole o JSON no analisador JSON online; a ferramenta coloca o cursor na localização do erro e destaca o número da linha e da coluna — essa etapa economiza 90% do esforço de olhar caractere por caractere.

2. Seis erros de alta frequência

1. Vírgula final

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

Há uma vírgula extra antes de }. A especificação JSON não permite vírgulas finais, enquanto literais de objeto JavaScript permitem, então configurações copiadas de código são as mais propensas a carregar uma. Correção: exclua a última vírgula; se esses dados já vivem em um arquivo JS, use a conversão JSON5 em vez de forçá-los para JSON.

2. Aspas simples e chaves sem aspas

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

Strings JSON só podem usar aspas duplas, e as chaves também precisam ser strings entre aspas duplas. Essas duas formas são a sintaxe relaxada de JSON5 / JavaScript, não JSON. Uma aspa dupla dentro de uma string precisa ser escrita como \", e uma barra invertida como \\.

3. Comentários

复制{
  // Timeout em milissegundos
  "timeout": 3000
}

A gramática da RFC 8259 não tem lugar para comentários. Ou você exclui os comentários, ou salva como .jsonc / .json5 e usa um analisador que suporte comentários. Para os prós e contras das várias "soluções de comentário", veja Como escrever comentários no JSON.

4. Quebras de linha cruas e caracteres de controle dentro de strings

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

Strings JSON não podem conter quebras de linha cruas, tabulações nem os caracteres de controle U+0000–U+001F; eles precisam ser escritos como \n, \t, \u0009. Ao inserir texto de várias linhas em JSON, escape-o primeiro em um editor ou trate-o de forma uniforme com Minificação e escape JSON.

5. Cabeçalho BOM

O UTF-8 salvo pelo Bloco de Notas do Windows carrega os três bytes EF BB BF. O JSON.parse informa Unexpected token quando encontra um BOM, e o olho não consegue vê-lo. Como identificar: inspecione o cabeçalho do arquivo em hexadecimal, ou copie o conteúdo para uma ferramenta online e veja se o primeiro caractere aparece como . Correção: salve como "UTF-8 sem BOM".

6. Conteúdo truncado

Um log que só imprimiu os primeiros 4096 caracteres, uma resposta de API cortada por um gateway, um download interrompido — a marca desta classe é "o erro está no fim" e as contagens de colchetes não batem. Conte os colchetes primeiro: se os fechamentos de { e [ não combinam, é truncamento, não erro de sintaxe. Nesse caso não corrija nada — vá buscar os dados completos.

3. Dois falsos alarmes envolvendo texto em chinês e escaping

O chinês vira \u4e2d\u6587: isso é escaping JSON válido, não texto embaralhado. Depois da análise, o valor volta a ser chinês; a forma \u só aparece quando você olha a string crua diretamente. Quando precisar mostrá-lo às pessoas, basta imprimi-lo com a ferramenta de formatação; só é preciso se preocupar com a estratégia de escape quando o chinês precisa sobreviver em uma URL ou em um log.

O chinês vira texto embaralhado como 涓枃: isso é um problema de codificação, não de JSON. Acontece quando bytes UTF-8 são decodificados como GBK, produzindo esse padrão regular de "três caracteres representando um caractere chinês". Verifique o Content-Type: application/json; charset=utf-8 do cabeçalho de resposta e se encoding='utf-8' é especificado explicitamente ao ler o arquivo.

4. Um fluxo de reparo de cinco minutos

1. Cole na ferramenta: use primeiro o analisador online para localizar o primeiro erro e corrija apenas um por vez;
2. Valide após cada correção: reanalise a cada alteração, para que corrigir vários pontos de uma vez não deixe novos erros mascararem o antigo;
3. Minifique uma vez: remova os espaços em branco com Minificar e analise de novo; isso distingue "erros estruturais" de "problemas de espaço em branco ou quebra de linha";
4. Compare a estrutura: se um erro surgir de repente após uma alteração, use JSON diff contra a versão anterior; a diferença geralmente é aquela vírgula;
5. Validação em nível de campo: se a sintaxe passa mas a camada de negócio rejeita (campo ausente, tipo errado), isso cai na validação JSON Schema, não em um problema de sintaxe.

5. Por que um de dois trechos JSON "aparentemente idênticos" é analisado e o outro não

A causa mais comum são caracteres invisíveis: a vírgula de largura total ，, as aspas de largura total “”, o espaço não separável U+00A0, o espaço de largura zero U+200B. Na tela eles são quase indistinguíveis de suas contrapartes de meia largura, mas nenhum deles faz parte da gramática JSON.

Só há uma maneira de saber: copie o conteúdo em torno do caractere suspeito e inspecione os pontos de código byte a byte. Executar o seguinte no console do navegador lista todos os caracteres que não são ASCII e estão fora dos intervalos chineses:

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

Se 0x201c (aspa dupla à esquerda), 0xff0c (vírgula de largura total) ou 0x00a0 aparecerem na saída, eles são o culpado.

6. Prevenir é mais barato que reparar

• Rode uma verificação de análise nos arquivos de configuração antes de commitar; uma linha no CI basta: node -e "JSON.parse(require('fs').readFileSync('config.json','utf8'))";
• Gere respostas de API com uma biblioteca de serialização; nunca concatenar strings à mão — strings montadas manualmente são a única origem de vírgulas finais e aspas faltantes;
• Ao registrar JSON, chame JSON.stringify primeiro em vez de interpolá-lo em um template, para que um payload pela metade não seja confundido com uma mensagem completa.

Perguntas frequentes

Como localizar rapidamente a posição de um erro de sintaxe JSON?

Pegue a posição ou linha/coluna informada pelo analisador; position é um deslocamento de caractere com base 0, não um número de linha, enquanto Java Jackson e Python informam a linha e a coluna diretamente. Cole o JSON no analisador JSON online e a ferramenta coloca o cursor na localização do erro e destaca a linha e a coluna. Se o erro estiver no início, verifique o cabeçalho do arquivo em busca de BOM e de caracteres invisíveis.

Por que configurações copiadas de código têm tanta propensão a trazer uma vírgula final?

A especificação JSON proíbe vírgulas finais enquanto literais de objeto JavaScript as permitem, então configurações copiadas de código JS facilmente trazem uma junto. A correção é simplesmente excluir a última vírgula; se os dados pertencem mesmo a um arquivo JS, mudar para a conversão JSON5 é mais adequado do que forçá-los para JSON.

Posso analisar um arquivo de configuração com comentários como JSON comum?

Não — a gramática da RFC 8259 não tem lugar para comentários, então analisá-lo diretamente gera um erro. Ou você exclui os comentários, ou salva como .jsonc / .json5 e usa um analisador que suporte comentários. Para os prós e contras das soluções de comentário, veja Como escrever comentários no JSON.