O Que É uma Byte Order Mark (BOM)? Explicado

Uma byte order mark (BOM) é uma sequência especial no exato início de um arquivo de texto que sinaliza sua codificação e ordem de bytes.

A byte order mark é um prefixo minúsculo e invisível que alguns editores adicionam na frente de um arquivo de texto. Ela deveria ajudar os leitores a detectar a codificação, mas na prática uma BOM perdida é uma causa frequente de falhas de CI desconcertantes - um script que "parece bom" mas dá erro logo na primeira linha. Saber que ela existe economiza horas de depuração.

O que é uma BOM

Uma byte order mark é uma sequência específica de bytes no início de um arquivo que indica sua codificação Unicode e, para codificações de múltiplos bytes, a ordem de bytes. É metadado, não conteúdo - é invisível quando o texto é exibido, mas os bytes estão realmente lá.

BOM em UTF-16 versus UTF-8

Para UTF-16 a BOM é genuinamente útil: ela diz ao leitor se os bytes são big-endian ou little-endian. Para UTF-8 não há ambiguidade de ordem de bytes, então uma BOM UTF-8 não serve a nenhum propósito real e é melhor omiti-la - ainda assim alguns editores do Windows a adicionam mesmo assim.

Por que uma BOM UTF-8 causa bugs

Muitas ferramentas não esperam uma BOM e tratam esses bytes iniciais como parte do conteúdo. Um shell script com uma BOM falha porque o interpretador engasga com lixo antes do shebang; um parser de JSON ou YAML pode rejeitar o arquivo; um cabeçalho de CSV ganha caracteres invisíveis. As mensagens de erro raramente mencionam a BOM.

BOMs em CI

Um script que roda localmente mas falha no runner com um críptico "command not found" ou erro de sintaxe na linha 1 é muitas vezes um problema de BOM. Uma regra de lint ou pre-commit que remove BOMs, ou uma verificação no CI que as rejeita, impede que o arquivo sequer chegue a um runner.

# Fail CI if any tracked file has a UTF-8 BOM
steps:
  - run: |
      if grep -rlP "^\xEF\xBB\xBF" --include="*.sh" .; then
        echo "BOM found in shell script"; exit 1
      fi

Conselho prático

Configure seu editor para salvar arquivos como UTF-8 sem BOM, especialmente para shell scripts, JSON, YAML e CSV. Quando um erro na primeira linha não fizer sentido, verificar se há uma BOM oculta deveria estar bem no topo da sua lista.

Principais conclusões

• Uma BOM são bytes iniciais invisíveis que sinalizam a codificação de um arquivo e, para UTF-16, sua ordem de bytes.
• Uma BOM UTF-8 é inútil e frequentemente quebra a análise de shell scripts, JSON, YAML e CSV.
• No CI, um erro desconcertante na primeira linha é muitas vezes uma BOM perdida - salve os arquivos como UTF-8 sem BOM.

Guias relacionados