O que é um arquivo JSON, com o que abri-lo e como editá-lo

Resumo da ópera: antes de abrir um arquivo JSON, confirme sua codificação e o BOM e depois verifique se a estrutura é apenas um objeto ou um array; após editar, sempre valide com um analisador em vez de olhar colchetes e vírgulas a olho nu.

É simplesmente um arquivo de texto puro com extensão .json, e até o Bloco de Notas consegue abri-lo. A verdadeira dor de cabeça não é "não abre", e sim que, depois de aberto, você não consegue ver o que quebrou.

1. O que realmente existe dentro de um arquivo JSON

Um arquivo JSON válido pode conter apenas uma de duas coisas: um objeto {...} ou um array [...]. Nada mais é permitido — sem declarações de variável, sem comentários, sem funções.

复制{
  "name": "order service",
  "port": 8080,
  "debug": false,
  "upstream": ["10.0.0.11", "10.0.0.12"],
  "timeout": null
}

Reconhecer três coisas na estrutura já basta:

A extensão do arquivo não determina o conteúdo: package.json, tsconfig.json e composer.json são todos a mesma coisa; ferramentas diferentes apenas combinaram de ler chaves diferentes deles.

2. Três formas de abri-lo, escolhidas pelo cenário

Só uma olhada rápida: abra no navegador. Arraste o arquivo para uma janela do Chrome ou Edge e o navegador o exibe como está; se uma extensão JSON Viewer estiver instalada, ele é formatado e tornando-se recolhível automaticamente.

Precisa editar o conteúdo: use um editor. VS Code, Sublime e Notepad++ trazem realce de sintaxe JSON e correspondência de colchetes, e Shift + Alt + F no VS Code formata o documento. Observe que o Bloco de Notas do Windows pode adicionar um BOM ao salvar, então suas alterações de configuração podem não entrar em vigor; é melhor evitá-lo.

Não quer instalar nada, só quer validar: use o formatador JSON online. Cole o conteúdo e você vê imediatamente números de linha e coluna, localização de erros e uma árvore recolhível; copie o resultado quando terminar. Os dados são processados localmente no navegador e não são enviados a nenhum servidor.

Arquivos grandes (dezenas de MB ou mais): não force a abertura em um editor. Abrir um arquivo JSON de 100 MB no VS Code vai travar até você questionar suas escolhas de vida; use a linha de comando para inspecionar a estrutura primeiro:

复制# Veja as primeiras 20 linhas para confirmar se é um array
head -n 20 data.json

# Use jq para listar as chaves de nível superior sem carregar o arquivo inteiro
jq -r 'keys[]' data.json | head

# Conte o comprimento do array
jq 'length' data.json

3. O que fazer quando o duplo clique abre texto embaralhado

Três causas, cada uma tratada de forma diferente:

1. Na verdade é um arquivo binário (por exemplo, um pacote compactado ou um arquivo de banco de dados exportado, com extensão .json). Use file data.json para ver o tipo real; não force que seja tratado como texto.
2. A codificação não é UTF-8. Texto em chinês codificado como GBK fica embaralhado em um ambiente UTF-8. Use "Reabrir com codificação" do editor para tentar GBK uma vez; se exibir corretamente, salve como UTF-8.
3. O arquivo foi criptografado ou compactado. O sintoma é PK (zip) ou um monte de sinais de interrogação no início; esses arquivos precisam primeiro ser descompactados ou descriptografados.

4. Como confirmar que nada quebrou após editar

O JSON não tem tolerância: uma vírgula faltando, uma vírgula a mais ou uma aspa faltando e o arquivo inteiro morre, e a localização do erro informada muitas vezes aponta para a linha seguinte. Por isso, você precisa validar após editar; não confie nos olhos.

As três ações de edição de alto risco, ordenadas pela frequência com que causam problemas:

A validação é simples: cole no validador online e procure texto vermelho, ou execute uma linha na linha de comando:

复制python3 -m json.tool config.json > /dev/null && echo OK

Se imprimir OK, o arquivo é válido. Se você também quer validar os tipos dos campos (por exemplo, port precisa ser número e name não pode estar vazio), escrever um JSON Schema é bem mais confiável do que o olho humano.

5. Como .json difere de seus parentes próximos

Não se surpreenda ao ver comentários em tsconfig.json; ele é na verdade tratado como .jsonc. Entregue o mesmo conteúdo ao JSON.parse e ele vai gerar um erro. Quando precisar converter entre eles, use JSON5 para JSON para remover comentários e vírgulas finais com um clique.

6. Quando é hora de trocar o formato de armazenamento

O JSON é adequado a cenários em que "a estrutura não é fixa, humanos precisam ler e o conteúdo atravessa linguagens". Se um arquivo passa de dezenas de MB, a estrutura dos campos é estável e você precisa de consultas condicionais, continuar com JSON é só arrumar problema para si mesmo — migre para SQLite, Parquet ou carregue em um banco de dados; a diferença de desempenho de leitura/gravação é de ordens de magnitude. Para os prós e contras específicos, veja Análise e streaming de JSON grande.

Perguntas frequentes

Como inspecionar um arquivo JSON grande demais para abrir?

Não force a abertura em um editor; abrir um arquivo JSON de 100 MB no VS Code vai travar até você questionar suas escolhas de vida. Use a linha de comando para inspecionar a estrutura primeiro: head -n 20 confirma se é um array, jq -r 'keys[]' lista apenas as chaves de nível superior e jq 'length' conta o comprimento do array. Nenhum desses comandos carrega o arquivo inteiro.

Por que minhas edições no Bloco de Notas impedem a configuração de entrar em vigor?

O Bloco de Notas do Windows pode adicionar um BOM ao salvar, e um arquivo com BOM falha na análise da configuração, então o conteúdo editado nunca entra em vigor. A recomendação do artigo é usar editores como VS Code, Sublime ou Notepad++, que trazem realce de sintaxe JSON e correspondência de colchetes. Se você já usou o Bloco de Notas, salve novamente como "UTF-8 sem BOM" e tente de novo.

Posso tratar um arquivo JSON como JSON5 e adicionar comentários?

Não — um analisador padrão não permite comentários em um arquivo .json e JSON.parse gera um erro imediatamente. Comentários pertencem a arquivos .jsonc ou .json5 lidos pelo analisador correspondente. Arquivos como tsconfig.json são na verdade tratados como .jsonc; entregue o mesmo conteúdo ao JSON.parse e ele falha.