encodeURI vs encodeURIComponent

JavaScript expõe duas funções globais com nomes quase iguais mas conjuntos diferentes de caracteres que deixam sem escape. Ambas tratam texto URI, com escopos de dados diferentes.

encodeURIComponent codifica “um componente só”

Use para valores de query, segmentos de path, identificadores de fragment e qualquer string que não deve injetar estrutura:

encodeURIComponent("a/b?c=1&d=2");
// "a%2Fb%3Fc%3D1%26d%3D2"

Note /, ?, &, = viram escape percentual para o valor permanecer opaco quando embutido.

Padrão típico ao montar query manualmente:

const q = new URLSearchParams({
  title: "Q&A / Notes",
  next: "https://example.com/a?x=1",
});
q.toString(); // title=Q%26A+%2F+Notes&next=https%3A%2F%2Fexample.com%2Fa%3Fx%3D1
// (URLSearchParams usa application/x-www-form-urlencoded; + para espaço)

Para strings montadas à mão, prefira URLSearchParams ou bibliotecas que já tratam separadores.

encodeURI preserva delimitadores URI

encodeURI assume que você passa uma URI quase completa e só precisa corrigir caracteres ilegais globalmente mantendo pontuação estrutural:

encodeURI("https://example.com/résumé?id=1#top");
// https://example.com/r%C3%A9sum%C3%A9?id=1#top

Não codifica ?, #, / quando aparecem — porque acredita que podem ser delimitadores reais. Isso é perigoso se seu “dado” inclui esses símbolos.

encodeURI("https://example.com/search?q=a/b");
// mantém a barra — pode quebrar expectativa do servidor se / era dado, não separador de path

Regra prática: não use encodeURI para proteger texto arbitrário de usuário; use encodeURIComponent (ou APIs de nível superior) por componente.

Guia rápido de decisão

Situação	Helper preferido
Segmento de path com / como dado	encodeURIComponent em cada segmento
URL inteira do usuário com delimitadores desconhecidos	Parse com URL, depois codifique cada parte
URI já estruturalmente correta, só acentos falham	Talvez encodeURI — ainda é mais claro normalizar host/path separado
Montagem repetida de APIs	Prefira URL + URLSearchParams, não concatenação

decodeURI vs decodeURIComponent

Cuidados simétricos:

decodeURIComponent("100%2525"); // pode dar "100%25" com uma passagem — cuidado com double-encoding upstream
decodeURI("http://host/%7Euser") → mantém delimitadores e decodifica escapes em outras posições

Se você misturar escopos de encode/decode, texto decodificado pode reintroduzir separadores (&, ?) que mudam o parse de parâmetros — armadilha clássica em open-redirect ou bypass de filtro quando refletido em HTML ou headers.