Codificador e decodificador de URL
Codifique texto para uso seguro em uma URL, ou decodifique uma string com codificação percentual de volta para texto simples — instantaneamente, no seu navegador.
Esta página foi traduzida do inglês com a ajuda de IA e conferida com o original. Ler a versão em inglês
- Grátis — Sem necessidade de cadastro
- Instantâneo — Os resultados são atualizados enquanto você digita
- Privado — Processado no seu navegador
Uma URL só pode conter um conjunto limitado de caracteres, e vários deles têm função estrutural: ? inicia a query string, & separa os parâmetros, # abre o fragmento e / divide os segmentos do caminho. A codificação percentual (percent-encoding) substitui qualquer outro caractere, e qualquer caractere reservado usado como dado, por um % seguido de dois dígitos hexadecimais. Esta ferramenta aplica essa transformação a um único componente e também a desfaz.
Como funciona
Codificar passa o seu texto por encodeURIComponent. Todo caractere fora do conjunto não reservado A–Z a–z 0–9 - _ . ! ~ * ' ( ) é convertido em bytes UTF-8, e cada byte é escrito como %XX. Um espaço vira %20, & vira %26 e é vira os dois bytes %C3%A9. A codificação nunca falha.
Decodificar usa decodeURIComponent. A operação falha, com uma mensagem clara, quando um % não é seguido de dois dígitos hexadecimais ou quando os bytes decodificados não formam UTF-8 válido — por exemplo, um %E9 isolado, que é Latin-1 e não UTF-8. Um texto sem nenhuma sequência percentual continua igual depois de decodificado.
A palavra-chave é componente. O codificador foi feito para um único valor, como um parâmetro da query string ou um segmento de caminho, e não para uma URL inteira. Passar https://example.com/a?b=c por ele produz https%3A%2F%2Fexample.com%2Fa%3Fb%3Dc, que é o resultado certo para embutir essa URL como valor de um parâmetro (um destino de redirecionamento, por exemplo) e o resultado errado se você queria um link utilizável.
O sinal de mais
Envios de formulário codificados como application/x-www-form-urlencoded escrevem o espaço como +, e o próprio + como %2B. Essa convenção é dos formulários HTML, não das URLs em geral. Esta ferramenta segue as regras de URI da RFC 3986, então um espaço é sempre %20 e um + passa sem alteração. Se um servidor reclamar que seus espaços chegaram como sinais de mais literais, o remetente aplicou a regra dos formulários e o destinatário esperava a regra de URI, ou vice-versa; a solução é deixar explícito qual regra cada lado aplica.
Codificar duas vezes
O bug mais comum é a codificação dupla: um valor que já contém %20 é codificado de novo e vira %2520. Isso acontece quando um framework codifica automaticamente e o desenvolvedor também codifica manualmente. Se, depois de decodificar uma vez, sua string ainda tiver sequências %XX, ela foi codificada duas vezes; decodifique de novo e remova uma das etapas de codificação no código.
O erro inverso é decodificar cedo demais. Um valor de parâmetro que contém & precisa continuar codificado até a query string ser dividida em pares; caso contrário, será lido como dois parâmetros.
Equivalente na linha de comando
O jq consegue codificar um valor, e a biblioteca padrão do Python cobre os dois sentidos:
jq -rn --arg s 'a b&c=d' '$s | @uri' # a%20b%26c%3Dd
python3 -c 'import urllib.parse as u,sys; print(u.unquote(sys.argv[1]))' 'a%20b%26c'Observe que o quote do Python deixa / sem codificar por padrão, ao contrário de encodeURIComponent; passe safe='' para obter o mesmo comportamento.
Saiba mais
Decidir o que vai no caminho, o que vai na query string e como devem ficar identificadores que contêm caracteres especiais faz parte do design de APIs; o guia de design de APIs REST aborda essas convenções. O fluxo authorization code do OAuth 2.0 é construído quase inteiramente com URLs de redirecionamento que carregam parâmetros codificados, e o guia de OAuth 2.0 mostra na prática como ficam um redirect_uri e um state codificados corretamente. Para bytes que precisam trafegar como texto fora de uma URL, use o codificador Base64.
Perguntas frequentes
- Qual é a diferença entre codificação de URL e codificação Base64?
- A codificação de URL (codificação percentual) substitui caracteres não seguros de uma URL por sequências %XX para que a URL permaneça válida; a codificação Base64 converte dados binários ou de texto arbitrários em uma representação ASCII compacta para transporte. Elas resolvem problemas diferentes e não são intercambiáveis.
- Por que a decodificação falha na minha entrada?
- Uma sequência de codificação percentual tem que ser um % seguido de exatamente dois dígitos hexadecimais válidos, e qualquer sequência UTF-8 multibyte deve estar completa. Um % isolado, dígitos hexadecimais inválidos ou uma sequência truncada farão a decodificação falhar — a mensagem de erro indica que a entrada não é uma codificação percentual válida.
- Isso codifica um + como espaço, como fazem os dados de formulário?
- Não. Esta ferramenta usa a semântica de encodeURIComponent/decodeURIComponent, que nunca converte entre + e espaço — essa conversão é específica dos corpos de formulário application/x-www-form-urlencoded, não dos componentes de URL em geral.