Codificador / Decodificador de URL

A codificação URL (percent-encoding) substitui caracteres inseguros ou ambíguos em uma URL por % seguido do valor do byte UTF-8 em hexadecimal. O modo Component usa encodeURIComponent() e codifica todo caractere reservado — correto para valores que você embute em uma query string ou caminho. O modo URL completa usa encodeURI(), que preserva caracteres estruturais da URL como :/?#&=.

Exemplo

Entrada:

hello world & café / 日本語

Codificado como Component:

hello%20world%20%26%20caf%C3%A9%20%2F%20%E6%97%A5%E6%9C%AC%E8%AA%9E

Codificado como URL completa:

hello%20world%20&%20caf%C3%A9%20/%20%E6%97%A5%E6%9C%AC%E8%AA%9E

Repare que o modo URL completa deixou & e / intactos porque têm significado estrutural em uma URL.

Erros comuns e armadilhas

A maioria dos problemas de codificação vem de escolher o modo errado ou rodar a ferramenta duas vezes sobre o mesmo input. Abaixo estão os casos mais comuns.

• Usar encodeURI para valores de consulta. encodeURI("a&b=c") devolve a&b=c (sem alteração), o que quebra a query string. Use o modo Component (encodeURIComponent) para os valores.
• Dupla codificação. Codificar hello%20world uma segunda vez produz hello%2520world. Decodifique primeiro ou pule uma camada.
• Esquecer o #. Um # dentro de um valor de consulta é tratado como início de fragmento se não for codificado como %23.
• Confusão com o sinal de mais. + significa espaço em corpos form-encoded, mas é um + literal em um caminho ou query de URL. Para enviar um sinal de mais real em um valor de consulta, codifique-o como %2B.
• Sequência de percentual malformada. Um % literal que nunca foi codificado faz o decodeURIComponent lançar URI malformed. Codifique o % como %25 ou remova os % soltos antes de decodificar.
• UTF-8 vs servidores legados Latin-1. Esta ferramenta sempre usa UTF-8. Alguns sistemas muito antigos esperam Latin-1 / windows-1252 — lá, é é %E9, não %C3%A9. Se você vê mojibake, a outra ponta não é UTF-8.

Qual é a diferença entre encodeURI e encodeURIComponent?

encodeURIComponent escapa tudo que não for letra, dígito ou um de -_.!~*'(), portanto é seguro para valores isolados de consulta e segmentos de caminho. encodeURI deixa intactos os caracteres reservados de URL como :/?#&=, então serve para codificar uma URL inteira que já tem estrutura. Use Component em 95% dos casos; use URL completa só quando tiver uma URL quase válida com alguns espaços ou Unicode soltos.

Quais caracteres realmente precisam ser codificados em uma query string?

Dentro de um valor, os delimitadores de query & e = precisam ser codificados (caso contrário parecem separadores). Espaço vira %20 ou +. O marcador de fragmento # precisa ser codificado. Além disso: /, ?, qualquer caractere não ASCII e caracteres de controle. encodeURIComponent cuida de tudo isso; encodeURI deixa &, =, /, ?, # sem codificar porque são estruturais.

Por que minha URL está sendo duplamente codificada?

Dupla codificação ocorre quando você codifica um valor já codificado. Um espaço vira %20, então o próprio % vira %25, resultando em %2520. Geralmente acontece por passar uma URL já codificada de novo pelo encodeURIComponent, ou por um framework que adiciona codificação automática em cima da sua codificação manual. Decodifique uma vez e recodifique limpo, ou pule uma camada.

Como a ferramenta lida com caracteres não ASCII como emojis ou letras acentuadas?

Os codificadores do JavaScript convertem caracteres não ASCII primeiro em bytes UTF-8 e depois codificam cada byte com percentual. Assim, é vira %C3%A9 (dois bytes) e um emoji como 😀 vira %F0%9F%98%80 (quatro bytes). A decodificação inverte o processo. É o comportamento padrão do RFC 3986 e funciona com qualquer servidor moderno.

Por que a decodificação falha com "URI malformed"?

decodeURIComponent lança erro ao ver uma sequência percentual inválida — um % solitário sem dois dígitos hex (por exemplo %ZZ ou apenas %), ou sequências de bytes UTF-8 inválidas (como %C3 sem um byte de continuação válido). Causas comuns: um % literal na entrada que nunca foi codificado, ou uma string já decodificada uma vez e que ainda contém sinais de porcentagem.

Espaços devem virar + ou %20?

Ambos são vistos na prática. %20 está correto em todo lugar — caminhos, query strings e fragmentos. O atalho + só significa "espaço" dentro do formato application/x-www-form-urlencoded usado em submissões de formulário HTML. Esta ferramenta usa %20 porque encodeURIComponent usa. Se você precisar especificamente de +, substitua %20 por + depois de codificar.