Base64 para UTF-8: decodificar Base64 em texto Unicode

Como decodificar Base64 para UTF-8

1. Cole o Base64 em Entrada · Base64. O Charset já vem em UTF-8.
2. Leia o resultado em Saída · texto. A linha de status mostra a contagem de bytes e o tipo de conteúdo detectado.
3. Se a linha de status disser “Alguns bytes não são UTF-8 válido”, o texto está em outro charset. Experimente Detectar automaticamente, Windows-1252 ou UTF-16LE.
4. Copiar saída copia o texto; Baixar salva os bytes decodificados sem alteração.

Para codificar na direção inversa, use UTF-8 para Base64.

Exemplos

As três últimas linhas são os problemas tratados abaixo: um charset errado, uma string cortada e um texto que já estava estragado antes de ser codificado.

UTF-8 inválido e o caractere de substituição

O UTF-8 tem regras rígidas: um byte acima de 7F precisa fazer parte de uma sequência de 2, 3 ou 4 bytes com um padrão fixo. Bytes que quebram o padrão não podem ser lidos como UTF-8. O decodificador troca cada sequência quebrada por U+FFFD (�) e mostra o aviso “Alguns bytes não são UTF-8 válido. Tente outro charset.” Nada é descartado em silêncio, então cada � marca o ponto exato de um problema.

Duas causas explicam quase todos os casos:

• Outro charset. Y2Fm6Q== contém 63 61 66 E9, que é café em ISO-8859-1 e Windows-1252. Troque o Charset e o texto aparece. A página do decodificador Base64 lista os sintomas comuns de cada charset.
• Uma string truncada. Se o Base64 foi cortado, por exemplo pelo limite de uma coluna no banco de dados ou de uma linha de log, o último caractere pode perder parte dos seus bytes. 8J+YgA== é um emoji completo; 8J+Y é o mesmo emoji sem o último byte e decodifica para um único �. Procure o valor completo na origem.

Texto codificado duas vezes (é e ’)

Quando a saída mostra é no lugar de é, ü no lugar de ü ou ’ no lugar de um apóstrofo curvo, a culpa não é do decodificador. Em algum ponto anterior, bytes UTF-8 foram lidos como Windows-1252 e salvos de novo como UTF-8, transformando cada caractere especial em dois ou três errados. O Base64 guarda fielmente esse texto danificado: Y2Fmw4PCqQ== é UTF-8 válido da string de sete bytes café.

Muitas vezes dá para reparar essa string no código desfazendo o erro: codifique o texto como Windows-1252 e decodifique os bytes como UTF-8. A correção de verdade fica no sistema que gravou o texto.

Marcas de ordem de bytes

Alguns editores, principalmente no Windows, começam arquivos UTF-8 com os bytes EF BB BF, uma marca de ordem de bytes (BOM). Em Base64, o arquivo passa a começar com 77u/. O decodificador reconhece a marca e a deixa fora do texto, enquanto Baixar mantém os bytes exatamente como eram. No código, talvez você precise removê-la por conta própria:

import base64

raw = base64.b64decode("77u/SGk=")
raw.decode("utf-8")       # '\ufeffHi'
raw.decode("utf-8-sig")   # 'Hi'

base64.b64decode("Y2Fm6Q==").decode("utf-8", errors="replace")   # 'caf�'

Sem errors="replace", o Python lança UnicodeDecodeError diante de bytes inválidos. Em JavaScript, new TextDecoder("utf-8", { fatal: true }) lança um TypeError em vez de inserir �, e o decodificador padrão remove o BOM, como esta ferramenta. Mais em Base64 em Python e Base64 em JavaScript.

Perguntas frequentes