Em resumo: a codificação de URL (percent-encoding) substitui caracteres inseguros por sequências %XX para que os links sobrevivam a espaços, acentos e símbolos. Um espaço vira %20, um e-comercial vira %26. O truque é saber quando codificar uma URL inteira em vez de um único valor de consulta — e que encodeURIComponent e encodeURI não são intercambiáveis.

Uma URL só pode conter com segurança um conjunto limitado de caracteres. Todo o resto — espaços, letras acentuadas e símbolos reservados como ?, &, # e = — precisa ser percent-encoded, ou o link quebra ou aponta para onde não devia.

O que o percent-encoding realmente faz

Cada caractere inseguro é substituído por um sinal de porcentagem seguido do seu valor de byte hexadecimal. Um espaço é %20, um e-comercial %26, uma interrogação %3F. A decodificação inverte o processo, devolvendo cada %XX válido ao caractere original.

%20 versus + para espaços

Ambos podem significar «espaço», mas não no mesmo lugar. %20 é o espaço percent-encoded usado em todo o caminho e na consulta de uma URL. O sinal de mais + significa espaço apenas no contexto application/x-www-form-urlencoded — envios de formulário e strings de consulta — e em outros lugares é tratado literalmente. Na dúvida, %20 é a escolha mais segura e universal.

encodeURIComponent versus encodeURI

É a distinção que confunde. Use encodeURIComponent para um único valor inserido numa URL — por exemplo o termo de busca em ?q=hello%20world. Ele codifica caracteres reservados como & e = para que não sejam confundidos com a estrutura da URL. Use encodeURI só numa URL completa, onde esses caracteres reservados precisam manter o significado estrutural. Codificar uma URL inteira com encodeURIComponent estragaria seus próprios :// e ?; codificar um único parâmetro com encodeURI deixa caracteres perigosos sem escape.

Quando codificar

  • Ao construir uma string de consulta a partir de entrada do usuário (termos de busca, filtros, nomes).
  • Ao colocar um link dentro de outro como parâmetro ?redirect= ou ?url=.
  • Ao lidar com nomes de arquivo ou caminhos que contêm espaços ou acentos.
  • Ao depurar um link que funciona localmente mas quebra ao ser compartilhado.

A codificação de URL não é Base64

Resolvem problemas diferentes. O percent-encoding torna seguros os caracteres inseguros dentro de uma URL; o Base64 recodifica dados binários numa string ASCII compacta, e sua saída ainda precisa de codificação de URL se for para um link. Escolher o errado produz links que parecem codificados mas não funcionam.

Um fluxo prático

Cole o valor bruto no Codificador / Decodificador de URL para codificar um parâmetro ou decodificar uma string %XX suspeita — ele decodifica as sequências válidas e sinaliza as inválidas em vez de corrompê-las em silêncio. Se o mesmo conteúdo passa também por Base64, verifique-o com o Codificador / Decodificador Base64 para aplicar os dois passos na ordem certa.

Erros comuns a evitar

  • Codificar uma URL completa com encodeURIComponent e quebrar sua estrutura.
  • Supor que + significa espaço em qualquer parte de uma URL.
  • Codificação dupla — passar de novo pelo codificador uma string já codificada.
  • Confundir o percent-encoding com o Base64.

Codifique as partes, não o todo, e um link com espaços, acentos ou uma URL aninhada viajará intacto.