¿Cuál es la diferencia entre encodeURI y encodeURIComponent?

¿Qué es encodeURI()?

encodeURI() es una función integrada de JavaScript diseñada para codificar un identificador uniforme de recursos (URI) completo. Convierte los caracteres que no son válidos en un URI en sus equivalentes percent-encoded, pero preserva de forma intencionada los caracteres que tienen un significado estructural dentro de un URI.

En concreto, encodeURI() no codifica los siguientes caracteres: A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #. Esto significa que la estructura general de la URL permanece intacta tras la codificación.

// encodeURI() preserva la estructura de la 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"
// Fíjate: :, /, ?, & y = NO se codifican

Este comportamiento hace que encodeURI() sea ideal cuando tienes una URL completa que puede contener espacios o caracteres no ASCII, pero cuyos caracteres estructurales (separador de protocolo, delimitadores de ruta, marcadores de la cadena de consulta) deben permanecer tal cual.

¿Qué es encodeURIComponent()?

encodeURIComponent() está diseñada para codificar un único componente de un URI, como el valor de un parámetro de consulta o un segmento de la ruta. A diferencia de encodeURI(), codifica prácticamente todos los caracteres especiales, incluidos aquellos que tienen un significado estructural en las URLs.

Los únicos caracteres que encodeURIComponent() no codifica son: A-Z a-z 0-9 - _ . ! ~ * ' ( ). Todo lo demás, incluidos /, ?, &, =, # y :, se somete a percent-encoding.

// encodeURIComponent() codifica todo salvo los caracteres no reservados
const value = 'Tom & Jerry / Friends?';
console.log(encodeURIComponent(value));
// "Tom%20%26%20Jerry%20%2F%20Friends%3F"
// Fíjate: &, / y ? SÍ se codifican

// Construir una URL con un 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 codifica los caracteres estructurales, nunca deberías usar encodeURIComponent() sobre una URL completa. Hacerlo codificaría el ://, todos los separadores de ruta / y el delimitador de consulta ?, dejando la URL inutilizable.

Diferencias clave de un vistazo

Característica	encodeURI()	encodeURIComponent()
Propósito	Codificar un URI completo	Codificar un componente de URI
Codifica /	No	Sí (%2F)
Codifica ?	No	Sí (%3F)
Codifica &	No	Sí (%26)
Codifica =	No	Sí (%3D)
Codifica #	No	Sí (%23)
Codifica :	No	Sí (%3A)
Codifica espacios	Sí (%20)	Sí (%20)
Codifica Unicode	Sí	Sí

Cuándo usar cada función

La regla es sencilla: usa encodeURI() cuando quieras codificar una URL completa manteniendo su estructura válida. Usa encodeURIComponent() cuando quieras codificar un único valor que se insertará dentro de una URL.

// Escenario 1: Codificar una URL completa con espacios
const fullUrl = 'https://example.com/my documents/file name.pdf';
const encoded = encodeURI(fullUrl);
// "https://example.com/my%20documents/file%20name.pdf"

// Escenario 2: Construir una URL a partir de sus 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"

// Escenario 3: Codificar una URL de redirección como parámetro
const redirectUrl = 'https://example.com/callback?token=abc';
const loginUrl = 'https://auth.example.com/login?redirect=' +
  encodeURIComponent(redirectUrl);
// La URL de redirección completa se codifica como el valor de un único parámetro

Errores comunes y cómo evitarlos

Error 1: Usar encodeURI() para los valores de parámetros de consulta. Como encodeURI() no codifica & ni =, usarla sobre el valor de un parámetro que contenga estos caracteres corromperá la estructura de la cadena de consulta.

// INCORRECTO
const bad = 'https://example.com/search?q=' + encodeURI('salt & pepper');
// "https://example.com/search?q=salt%20&%20pepper"
// El servidor ve q="salt " y un parámetro adicional " pepper"

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

Error 2: Usar encodeURIComponent() sobre una URL completa. Esto destruye la estructura de la URL al codificar todas las barras, dos puntos e interrogaciones.

// INCORRECTO
console.log(encodeURIComponent('https://example.com/path?key=value'));
// "https%3A%2F%2Fexample.com%2Fpath%3Fkey%3Dvalue"
// ¡Esto ya no es una URL válida!

// CORRECTO
console.log(encodeURI('https://example.com/path?key=value'));
// "https://example.com/path?key=value" (ya es válida, no hay nada que codificar)

Error 3: Doble codificación. Si una cadena ya está percent-encoded, codificarla de nuevo codificará los signos %, convirtiendo %20 en %2520. Comprueba siempre si un valor ya ha sido codificado antes de aplicar funciones de codificación.

Una alternativa moderna y más segura son las APIs URL y URLSearchParams, que gestionan la codificación automáticamente y te ayudan a evitar por completo estos inconvenientes.