Codificação URL: codifique parâmetros de consulta e caminhos

A codificação percentual substitui caracteres inseguros por %XX para que qualquer texto seja seguro em uma URL. Saiba quais caracteres escapar e como decodificá-los.

O que é codificação percentual

Os caracteres que não podem aparecer em uma URL são trocados por um sinal de porcento e dois dígitos hexadecimais. Um espaço vira %20 e um e-comercial vira %26.

encodeURIComponent vs encodeURI

Use encodeURIComponent para um único valor de query ou segmento de caminho — ele escapa /, ?, & e =. Use encodeURI só na URL inteira, onde esses caracteres são estruturais e precisam sobreviver.

A armadilha do + e do %20

Em query strings, um espaço pode aparecer como + (form encoding) ou como %20. decodeURIComponent não transforma + em espaço, então substitua os + antes de decodificar dados de formulário.

Codificação dupla

Codificar de novo uma string já codificada transforma %20 em %2520. Se você vir sequências %25 na saída, o valor foi codificado duas vezes — decodifique repetidamente até parar de mudar.

Caracteres reservados vs não reservados

A RFC 3986 separa os caracteres de URL em reservados (gen-delims como : / ? # e sub-delims como & =) e não reservados (letras, dígitos, - . _ ~). Os não reservados nunca precisam de codificação. Os reservados só precisam quando aparecem dentro de um valor, e não como estrutura de URL.

Codificar uma URL inteira vs um único valor

encodeURI serve para URLs inteiras: ele deixa : / ? # & = como estão, preservando a estrutura. encodeURIComponent serve para um único valor que vai para um segmento de caminho ou parâmetro — ele escapa esses caracteres estruturais para que o valor não escape do lugar dele.

Montar query strings com segurança via código

Prefira URLSearchParams (navegador) ou url.URLSearchParams (Node) em vez de concatenar strings. As duas APIs codificam chaves e valores corretamente, lidam com parâmetros multi-valor e evitam o erro mais comum — esquecer de codificar um parâmetro que por acaso contém & ou =.