Qual é a Diferença Entre encodeURI e encodeURIComponent?

O que é encodeURI()?

encodeURI() é uma função nativa do JavaScript projetada para codificar um Identificador Uniforme de Recursos (URI) completo. Ela converte os caracteres que não são válidos numa URI nos seus equivalentes percent-encoded, mas preserva intencionalmente os caracteres que têm significado estrutural dentro de uma URI.

Especificamente, encodeURI() não codifica os seguintes caracteres: A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #. Isto significa que a estrutura geral da URL permanece intacta após a codificação.

// encodeURI() preserva a estrutura da URL
const url = 'https://example.com/my page?name=John Doe&city=New York';
console.log(encodeURI(url));
// "https://example.com/my%20page?name=John%20Doe&city=New%20York"
// Repare: :, /, ?, & e = NÃO são codificados

Este comportamento torna encodeURI() ideal quando você tem uma URL completa que pode conter espaços ou caracteres não-ASCII, mas cujos caracteres estruturais (separador de protocolo, delimitadores de caminho, marcadores da string de consulta) devem permanecer como estão.

O que é encodeURIComponent()?

encodeURIComponent() foi projetada para codificar um único componente de uma URI, como o valor de um parâmetro de consulta ou um segmento de caminho. Ao contrário de encodeURI(), ela codifica quase todos os caracteres especiais, incluindo aqueles que têm significado estrutural nas URLs.

Os únicos caracteres que encodeURIComponent() não codifica são: A-Z a-z 0-9 - _ . ! ~ * ' ( ). Todo o resto, incluindo /, ?, &, =, # e :, é percent-encoded.

// encodeURIComponent() codifica tudo, exceto os caracteres não reservados
const value = 'Tom & Jerry / Friends?';
console.log(encodeURIComponent(value));
// "Tom%20%26%20Jerry%20%2F%20Friends%3F"
// Repare: &, / e ? SÃO codificados

// Construindo uma URL com um parâmetro de consulta
const url = 'https://example.com/search?q=' + encodeURIComponent(value);
// "https://example.com/search?q=Tom%20%26%20Jerry%20%2F%20Friends%3F"

Como ela codifica os caracteres estruturais, você nunca deve usar encodeURIComponent() numa URL completa. Fazer isso codificaria o ://, todos os separadores de caminho / e o delimitador de consulta ?, tornando a URL inutilizável.

Principais Diferenças num Relance

Característica	encodeURI()	encodeURIComponent()
Finalidade	Codificar uma URI completa	Codificar um componente da URI
Codifica /	Não	Sim (%2F)
Codifica ?	Não	Sim (%3F)
Codifica &	Não	Sim (%26)
Codifica =	Não	Sim (%3D)
Codifica #	Não	Sim (%23)
Codifica :	Não	Sim (%3A)
Codifica espaços	Sim (%20)	Sim (%20)
Codifica Unicode	Sim	Sim

Quando Usar Cada Função

A regra é simples: use encodeURI() quando quiser codificar uma URL completa mantendo a sua estrutura válida. Use encodeURIComponent() quando quiser codificar um único valor que será inserido numa URL.

// Cenário 1: Codificando uma URL completa com espaços
const fullUrl = 'https://example.com/my documents/file name.pdf';
const encoded = encodeURI(fullUrl);
// "https://example.com/my%20documents/file%20name.pdf"

// Cenário 2: Construindo uma URL a partir de partes
const baseUrl = 'https://api.example.com/search';
const query = 'price >= 100 & category = books';
const finalUrl = baseUrl + '?q=' + encodeURIComponent(query);
// "https://api.example.com/search?q=price%20%3E%3D%20100%20%26%20category%20%3D%20books"

// Cenário 3: Codificando uma URL de redirecionamento como parâmetro
const redirectUrl = 'https://example.com/callback?token=abc';
const loginUrl = 'https://auth.example.com/login?redirect=' +
  encodeURIComponent(redirectUrl);
// A URL de redirecionamento inteira é codificada como o valor de um único parâmetro

Erros Comuns e Como Evitá-los

Erro 1: Usar encodeURI() para valores de parâmetros de consulta. Como encodeURI() não codifica & nem =, usá-la num valor de parâmetro que contenha esses caracteres irá corromper a estrutura da string de consulta.

// ERRADO
const bad = 'https://example.com/search?q=' + encodeURI('salt & pepper');
// "https://example.com/search?q=salt%20&%20pepper"
// O servidor interpreta q="salt " e um parâmetro extra " pepper"

// CORRETO
const good = 'https://example.com/search?q=' + encodeURIComponent('salt & pepper');
// "https://example.com/search?q=salt%20%26%20pepper"

Erro 2: Usar encodeURIComponent() numa URL completa. Isto destrói a estrutura da URL ao codificar todas as barras, dois-pontos e pontos de interrogação.

// ERRADO
console.log(encodeURIComponent('https://example.com/path?key=value'));
// "https%3A%2F%2Fexample.com%2Fpath%3Fkey%3Dvalue"
// Isto já não é uma URL válida!

// CORRETO
console.log(encodeURI('https://example.com/path?key=value'));
// "https://example.com/path?key=value" (já é válida, nada a codificar)

Erro 3: Codificação dupla. Se uma string já estiver percent-encoded, codificá-la novamente irá codificar os sinais de %, transformando %20 em %2520. Verifique sempre se um valor já foi codificado antes de aplicar as funções de codificação.

Uma alternativa moderna e mais segura são as APIs URL e URLSearchParams, que tratam da codificação automaticamente e ajudam a evitar completamente essas armadilhas.