Codificador e decodificador de URL

A codificação percentual em um parágrafo

Uma URL só pode conter um conjunto pequeno de caracteres. Todo o resto é escrito como um sinal de porcentagem seguido dos dois dígitos hexadecimais do seu byte: um espaço é %20, o sinal # é %23. Os caracteres fora do ASCII são convertidos primeiro para UTF-8 e só então escapados byte a byte, então é vira %C3%A9 — dois escapes para um único caractere. Uma ferramenta que em vez disso produz %E9 está usando Latin-1 e vai quebrar com qualquer coisa moderna.

Os caracteres que nunca precisam de escape

A RFC 3986 os chama de não reservados: as letras A–Z e a–z, os dígitos 0–9 e os quatro sinais - . _ ~. Eles significam a mesma coisa escapados ou não, então escapá-los é legal mas inútil, e faz duas URLs idênticas parecerem diferentes para um cache.

Depois vêm os caracteres reservados — / ? # [ ] @ : $ & ' ( ) * + , ; = — que são a pontuação que dá estrutura a uma URL. Se eles precisam de escape ou não depende inteiramente de onde estão. Dentro de um valor, um & solto abre um parâmetro novo e corta os seus dados em silêncio. Na URL em si, ele está fazendo o trabalho dele.

Qual dos dois codificadores você quer

Essa é a distinção que o seletor de modo acima está fazendo, e é a mesma que existe por trás das duas funções do JavaScript:

• Um único valor (encodeURIComponent) escapa também os caracteres estruturais. Use para o valor de um parâmetro, um segmento de caminho, um dado digitado por uma pessoa. Rode isso em um endereço inteiro e você obtém https%3A%2F%2Fexample.com, que é o comportamento correto e completamente inútil como link.
• URL inteira (encodeURI) deixa a estrutura intacta e escapa apenas o que nunca pode aparecer cru, como espaços e caracteres acentuados. Use para consertar uma URL que alguém digitou com um espaço no meio. Nunca use em um dado que você vai inserir, porque ela deixa um & intacto e permite que o valor escape do seu parâmetro.

O sinal de mais é genuinamente ambíguo

No formato application/x-www-form-urlencoded — o que os formulários HTML enviam e, por isso, a cara da maioria das query strings — um espaço é escrito como +. Na RFC 3986, que rege as URLs em geral, + é um sinal de mais literal. Os dois estão corretos no seu próprio contexto, e uma query string não diz qual das duas regras a produziu.

A consequência prática: um número de telefone em uma query string é uma armadilha. ?tel=+44123 chega a muitos servidores como " 44123". Se um valor pode conter um sinal de mais, codifique-o como %2B e pare de confiar em qualquer uma das duas convenções. A tabela de parâmetros acima decodifica + como espaço, porque esse é o caso mais comum, o que significa que ela mostra a coisa errada para valores em que o mais era literal.

A codificação dupla, e por que não dá para desfazê-la de forma confiável

Codifique uma string duas vezes e %20 vira %2520, porque o próprio sinal de porcentagem é escapado. A ferramenta avisa quando vê esse padrão, e quando uma decodificação deixa escapes para trás. O que ela não consegue fazer é dizer se aquilo foi um erro: uma URL que contém o texto literal 100%25 é uma coisa perfeitamente válida de guardar. Quando um dado com codificação dupla chega a um banco de dados, a ambiguidade é permanente.

O que esta ferramenta não resolve

• Nomes de domínio internacionalizados. Um nome de host como müller.de não é codificado com porcentagem: ele é convertido com punycode para xn--mller-kva.de, um algoritmo completamente diferente. Escapes percentuais dentro de um nome de host são inválidos, e esta ferramenta vai produzi-los sem reclamar se você pedir.
• Normalização. Ela não passa o esquema para minúsculas, não colapsa ../, não ordena parâmetros nem resolve uma URL relativa a partir de uma base.
• Validação. A saída está escapada corretamente; isso não quer dizer que ela seja um endereço que funciona.
• Barras codificadas dentro do caminho. %2F não é a mesma coisa que /, e muitos servidores e proxies rejeitam ou normalizam isso em silêncio antes que o seu código chegue a vê-lo. Se um segmento de caminho precisa conter uma barra, teste contra a stack real em vez de confiar no escape.

Última atualização 19 de setembro de 2026