Um BOM quebra a análise JSON

Resumo da ópera: verifique se os três primeiros bytes são EF BB BF e salve novamente como UTF-8 sem BOM; no servidor, remova um U+FEFF inicial antes de analisar qualquer arquivo enviado ou de terceiros, em vez de depurar a falha depois.

Sim — e ele produz o mais confuso de todos os erros de análise, porque o arquivo parece perfeitamente bem.

O que você vê

复制SyntaxError: Unexpected token  in JSON at position 0
Unexpected character '\uFEFF'

O caractere na mensagem é invisível. Posição 0 significa o primeiro byte.

cat não mostra nada incomum. hexdump -C file.json | head -1 mostra:

复制00000000  ef bb bf 7b 0a 20 20 22  61 22 3a 20 31 0a 7d 0a  |...{  "a": 1.}.|

7b é {. Os três bytes antes dele são o BOM.

De onde vêm os BOMs

A marca de ordem de bytes existia para UTF-16, onde a ordem dos bytes realmente variava. O UTF-8 tem uma única ordem de bytes, então o BOM é puro overhead — e ainda assim o Bloco de Notas do Windows, algumas exportações do Excel e algumas IDEs mais antigas o gravam por padrão.

A RFC 8259 é inequívoca: o JSON trocado entre sistemas precisa ser UTF-8, e as implementações não devem acrescentar um BOM. Os analisadores podem ignorar um BOM inicial, mas não são obrigados. Navegadores e Node escolhem não ignorar.

Três formas de se livrar dele

Salve sem BOM. No VS Code, clique na codificação na barra de status e escolha "Salvar com codificação → UTF-8", não "UTF-8 com BOM".

Remova pelo shell.

复制sed -i '1s/^\xEF\xBB\xBF//' data.json

Remova na leitura. Esta é a correção durável para qualquer coisa que aceite arquivos enviados ou de terceiros:

复制const text = require('node:fs').readFileSync('data.json', 'utf8').replace(/^\uFEFF/, '');
JSON.parse(text);

Em Python, open(path, encoding='utf-8-sig') cuida disso automaticamente.

Dois problemas parecidos

• Espaço de largura zero (U+200B) — capturado ao copiar JSON de uma página web; sintoma idêntico, ponto de código diferente.
• Aspas de largura total — um IME chinês transforma "key" em “key”, que parece quase idêntico mas falha como Unexpected token “.

Os três são bugs de caractere invisível. O diagnóstico é sempre o mesmo: despeje os primeiros bytes em hexadecimal em vez de encarar o texto.

Perguntas frequentes

Como saber se um arquivo começa com BOM?

cat não mostra nada, então rode hexdump -C file.json | head -1. Se a saída começar com ef bb bf, o arquivo tem BOM; em um arquivo UTF-8 limpo, 7b (o {) deve vir primeiro.

Por que o erro sempre aponta para linha 1, coluna 1?

O BOM fica antes de tudo, então o primeiro caractere que o analisador lê é U+FEFF. A falha cai no início do arquivo, o que faz o arquivo parecer vazio.

Devo remover o BOM antes de analisar?

Sim. Quando um servidor lê configuração ou analisa arquivos enviados, remova primeiro um U+FEFF inicial — replace(/^\uFEFF/, '') no Node, encoding='utf-8-sig' no Python — o que é bem mais barato do que diagnosticar depois.

Leitura adicional

• Diagnóstico de erros de análise JSON
• O que é um arquivo JSON e como abrir um