JavaScript incluye dos funciones para codificar texto con porcentaje: encodeURI y encodeURIComponent. Sus nombres son casi idénticos y también lo son sus resultados con cadenas simples, y por eso los desarrolladores las confunden. Elegir la equivocada produce enlaces que se rompen sin avisar solo cuando la entrada contiene ciertos caracteres.
La respuesta corta
Usa encodeURIComponent para valores individuales, como un parámetro de consulta o un segmento de ruta. Usa encodeURI solo cuando ya tienes una URL completa y solo necesitas limpiar caracteres inseguros dejando intacta su estructura. En el código del día a día, encodeURIComponent es la que usarás nueve de cada diez veces.
Qué deja intacto cada función
Ambas funciones dejan sin tocar los caracteres sin reservar: letras, dígitos y - _ . ~. También dejan unos símbolos extra: ! ' ( ) *.
La diferencia está en los caracteres reservados. encodeURI supone que le entregas una URL completa y por eso no toca los caracteres que dan estructura a una URL: ; , / ? : @ & = + $ #. encodeURIComponent supone que le entregas un único dato, así que también codifica todos esos.
Este es el mismo texto procesado por ambas:
const texto = "a/b?c=d&e f";
encodeURI(texto); // "a/b?c=d&e%20f"
encodeURIComponent(texto); // "a%2Fb%3Fc%3Dd%26e%20f"
encodeURI solo codifica el espacio, porque la barra, el signo de interrogación, el igual y el ampersand parecen sintaxis legítima de URL. encodeURIComponent escapa todos ellos, que es lo que quieres cuando ese texto es un valor y no parte del esqueleto de la URL.
El error clásico
Imagina construir un enlace de búsqueda con la entrada del usuario:
const q = "sal & pimienta";
const mal = "https://example.com/search?q=" + encodeURI(q);
// ...?q=sal%20&%20pimienta
El ampersand sobrevive, así que el servidor lee la consulta como q=sal seguida de un segundo parámetro vacío. La versión correcta es:
const bien = "https://example.com/search?q=" + encodeURIComponent(q);
// ...?q=sal%20%26%20pimienta
Siempre que un valor pueda contener &, =, #, + o /, encodeURI es la herramienta equivocada.
El error contrario
Llamar a encodeURIComponent sobre una URL completa es igual de malo:
encodeURIComponent("https://example.com/a b");
// "https%3A%2F%2Fexample.com%2Fa%20b"
Los dos puntos y las barras se escapan, así que el resultado ya no es un enlace utilizable. Solo es válido como valor dentro de otra URL, por ejemplo un parámetro de redirección: ?next=https%3A%2F%2Fexample.com%2Fa%20b.
Decodificación
Las funciones correspondientes son decodeURI y decodeURIComponent. Se aplica la misma regla. decodeURIComponent revierte todo, mientras que decodeURI deja intactas las secuencias de escape de caracteres reservados como %2F. Ambas lanzan un URIError si la entrada contiene una secuencia de porcentaje mal formada, como un % solitario, así que envuelve la decodificación de entradas no confiables en un bloque try.
Una tercera opción: URLSearchParams y URL
El JavaScript moderno ofrece un enfoque más limpio que evita por completo la codificación manual:
const url = new URL("https://example.com/search");
url.searchParams.set("q", "sal & pimienta");
url.toString(); // "https://example.com/search?q=sal+%26+pimienta"
URLSearchParams codifica los valores por ti, usando la convención de formulario donde los espacios se convierten en +. Es la forma más segura de construir cadenas de consulta porque no puedes olvidarte de codificar.
Una guía rápida de decisión
- Un valor individual en una cadena de consulta o ruta:
encodeURIComponent. - Una URL completa que puede contener espacios o acentos:
encodeURI. - Construir una URL a partir de partes:
URLyURLSearchParams. - Una URL pasada como parámetro de otra URL:
encodeURIComponent.
Para ver la diferencia con tu propio texto, alterna entre las opciones de componente y URL completa en el codificador y decodificador de URL y compara el resultado.