Resolver completamente a codificação incorreta em CSV! Conhecimentos fundamentais sobre códigos de caracteres, BOM e códigos de quebra de linha

Acredito que todo desenvolvedor já enfrentou a situação de abrir um arquivo CSV e encontrar caracteres corrompidos. Especialmente com CSVs contendo japonês, problemas frequentemente ocorrem devido a diferenças na codificação de caracteres. Este artigo reúne conhecimentos para entender fundamentalmente as causas da corrupção de caracteres e resolvê-las com confiabilidade.

Noções básicas de codificação: UTF-8 vs Shift_JIS

As codificações de caracteres que causam problemas em arquivos CSV em japonês são principalmente as duas a seguir.

UTF-8

É o padrão web atual e um código de caracteres baseado em Unicode que pode lidar com caracteres de todo o mundo. UTF-8 é o padrão em Linux, macOS e aplicações web modernas. É uma codificação de comprimento variável de 1 a 4 bytes por caractere, e caracteres ASCII são representados como 1 byte.

Shift_JIS（CP932）

É uma codificação de caracteres em japonês usada em aplicativos legados do Windows e versões antigas do Excel. Mais precisamente, em ambientes Windows é usado CP932 (extensão de Shift_JIS pela Microsoft), e alguns caracteres dependentes de dispositivo (números circulados, algarismos romanos, etc.) só podem ser tratados em CP932.

Por que ocorre corrupção de caracteres

A causa fundamental da distorção de caracteres é simples. É porque a codificação ao escrever o arquivo não corresponde à codificação ao lê-lo.

Por exemplo, quando um aplicativo web exporta um CSV em UTF-8 e o usuário o abre no Excel, os caracteres ficam corrompidos. Isso ocorre porque o Excel interpreta o arquivo como Shift_JIS (CP932) por padrão no ambiente de idioma japonês.

Função da BOM (Byte Order Mark)

A BOM é um marcador de alguns bytes adicionado ao início do arquivo que serve como indicador da codificação de caracteres. A BOM UTF-8 é composta por 3 bytes: <code>0xEF 0xBB 0xBF</code>.

O ponto importante é que <strong>é necessário BOM para abrir corretamente um CSV UTF-8 no Excel</strong>. Se você abrir um CSV UTF-8 sem BOM no Excel, será interpretado como Shift_JIS e terá caracteres distorcidos.

// PHP で BOM 付き UTF-8 CSV を出力する例
header('Content-Type: text/csv; charset=UTF-8');
header('Content-Disposition: attachment; filename="data.csv"');

// BOM を出力
echo "\xEF\xBB\xBF";

$fp = fopen('php://output', 'w');
fputcsv($fp, ['名前', 'メール', '部署']);
fputcsv($fp, ['田中太郎', 'tanaka@example.com', '開発部']);
fclose($fp);

# Python で BOM 付き UTF-8 CSV を出力する例
import csv

with open('data.csv', 'w', encoding='utf-8-sig', newline='') as f:
    writer = csv.writer(f)
    writer.writerow(['名前', 'メール', '部署'])
    writer.writerow(['田中太郎', 'tanaka@example.com', '開発部'])

No entanto, a BOM também tem pontos de atenção. Alguns programas e scripts de shell tratam a BOM como um caractere inválido, o que pode causar erros. É mais seguro não adicionar BOM a CSVs processados em respostas de API ou em programas.

Problema de código de quebra de linha

Um problema comum junto com a codificação incorreta de caracteres em CSV é a diferença nos códigos de quebra de linha.

• <strong>CRLF</strong>（<code>\r\n</code>）— Padrão do Windows
• <strong>LF</strong>（<code>\n</code>）— Padrão do Linux / macOS
• <strong>CR</strong>（<code>\r</code>）— Mac OS antigo (raramente usado atualmente)

Em RFC 4180, o código de quebra de linha CSV é definido como CRLF. Porém, na prática, muitas ferramentas podem processar CSV com apenas LF sem problemas. O Excel e alguns sistemas legados são mais propensos a problemas.

Ferramentas de linha de comando são úteis para verificar códigos de quebra de linha.

# file コマンドで確認
file data.csv
# 出力例: data.csv: UTF-8 Unicode (with BOM) text, with CRLF line terminators

# xxd で先頭バイトを確認（BOM の有無）
xxd data.csv | head -3

Gráfico de solução prática

Abaixo resumimos as configurações ideais de acordo com o uso do CSV.

Arquivo CSV para teste

Para verificar se sua aplicação consegue processar corretamente arquivos CSV com diversas codificações de caracteres, use os arquivos de teste do DevLab.

• <a href="/ja/files/encoding/">Arquivo CSV de teste por codificação de caracteres</a> — UTF-8 (com/sem BOM), Shift_JIS, EUC-JP, etc.
• <a href="/ja/files/newline/">Arquivos de teste por código de quebra de linha</a> — Vários arquivos CRLF, LF, CR
• <a href="/ja/files/csv/">Lista de arquivos CSV de teste</a> — Arquivos CSV de vários tamanhos

Resumo

Os problemas de codificação incorreta em CSV podem ser resolvidos com certeza se você entender corretamente os 3 elementos: códigos de caracteres, BOM e códigos de quebra de linha. Para Excel, o padrão é UTF-8 com BOM e quebra CRLF; para processamento de programas, é UTF-8 sem BOM e quebra LF. Usando os vários arquivos de teste do DevLab, verifique se seu aplicativo pode processar corretamente cada padrão.