encodeURI vs encodeURIComponent: cuál usar y por qué

Respuesta breve

Usa encodeURIComponent para un valor individual que vas a insertar en una ruta, query o fragmento; usa encodeURI solo cuando ya tienes una URL completa y quieres conservar sus separadores estructurales. La opción más segura es construir la dirección con la API URL y URLSearchParams, no concatenar cadenas ya codificadas.

La diferencia es qué caracteres se conservan

Una URL contiene estructura: https://, barras de ruta, ?, pares separados por &, asignaciones con = y un fragmento tras #. encodeURI conserva muchos de esos símbolos porque presupone que forman parte de una URL completa.

encodeURIComponent presupone que la entrada es solo una pieza. Por eso codifica caracteres como ?, &, = y / que podrían alterar la estructura si aparecen dentro de un valor.

El codificador URL permite comparar el modo componente con el modo URL completa y muestra el resultado sin enviarlo a un servidor.

Ejemplo con un parámetro de búsqueda

Quieres construir una query cuyo valor sea pan & aceite:

https://ejemplo.test/buscar?q=pan%20%26%20aceite

Si aplicas encodeURI únicamente al valor, el & permanece visible y el servidor puede interpretarlo como el inicio de otro parámetro. Con encodeURIComponent, el ampersand se convierte en %26 y sigue siendo parte del valor.

Una alternativa más clara es:

const url = new URL('https://ejemplo.test/buscar');
url.searchParams.set('q', 'pan & aceite');

Así la API distingue datos y estructura por ti.

Ejemplo con una URL completa

Para https://ejemplo.test/a b?q=café#parte 1, encodeURI conserva esquema, host, /, ?, = y #, y codifica espacios o caracteres no permitidos. En cambio, encodeURIComponent codifica toda la cadena como un solo valor; el resultado sirve para incrustar esa URL dentro de otra, no para navegar directamente a ella.

Incluso encodeURI no valida que la dirección tenga el host o el protocolo que esperas. Parsear con new URL() permite inspeccionar componentes y aplicar una política de esquemas antes de usarla.

Rutas y fragmentos también son componentes

Un segmento de ruta con datos del usuario debe codificarse como componente. Si el valor es informe/2026, conservar / crearía dos segmentos. El resultado correcto como un único segmento es informe%2F2026.

Lo mismo ocurre con un fragmento o un nombre de parámetro. La palabra «componente» no significa solo «valor de query»: significa cualquier dato que no deba introducir nuevos delimitadores en el contexto donde se inserta.

Errores frecuentes

• Aplicar encodeURIComponent a una URL completa y luego intentar abrirla.
• Usar encodeURI en un valor que contiene &, # o =.
• Codificar una cadena que ya contiene %HH, creando %25HH.
• Decodificar toda una URL con decodeURIComponent y convertir %26 en un delimitador antes de separar parámetros.
• Esperar que estas funciones produzcan el formato de formulario, donde un espacio suele escribirse como +.

Las funciones ECMAScript y sus conjuntos de caracteres están definidos en la especificación de ECMAScript.

Regla práctica

Empieza por la unidad más pequeña: conserva los valores sin codificar en tu programa, usa URLSearchParams para queries y codifica un segmento solo en el límite donde se inserta. Si recibes una URL completa, no la decodifiques y vuelvas a codificar sin motivo; analiza sus partes. Esta separación reduce la doble codificación y evita que datos controlados por el usuario se conviertan accidentalmente en estructura.