Las URL solo pueden contener un conjunto restringido de caracteres ASCII. Todo lo demás —espacios, acentos, emojis y la puntuación que las URL usan estructuralmente— debe escribirse como un signo de porcentaje seguido del valor del byte en hexadecimal. Eso es toda la codificación porcentual. Lo interesante es saber qué caracteres codificar, porque codificar de más rompe una URL igual de bien que codificar de menos.
Hay dos codificadores, y elegir el equivocado rompe cosas
JavaScript te da encodeURI y encodeURIComponent, y difieren en exactamente once caracteres: # $ & + , / : ; = ? @. encodeURI los deja en paz; encodeURIComponent los escapa.
Esa lista no es arbitraria: son precisamente los caracteres que significan algo estructural en una URL. La barra separa segmentos de ruta, el interrogante abre la consulta, el ampersand separa parámetros, la almohadilla inicia el fragmento. Así que la regla se deduce sola: usa encodeURI cuando tengas una URL entera y quieras dejar intacto su esqueleto. Usa encodeURIComponent cuando tengas un solo valor a punto de insertarse en una URL: un parámetro de consulta, un segmento de ruta.
Si los inviertes, el fallo es silencioso. Codifica una URL entera con encodeURIComponent y obtendrás una cadena donde https%3A%2F%2F ya no es un esquema, y nadie la descargará. Codifica un valor de consulta con encodeURI y un valor que contenga & se parte en dos parámetros sin decir nada, lo que no es solo un error: es el mecanismo de la inyección de parámetros de consulta. Esta herramienta escapa el conjunto completo de componente, que es el valor por defecto seguro para el caso común: codificar un valor.
El signo más no es un espacio, salvo cuando lo es
Esta es la trampa más sutil de todo el asunto, y es genuinamente ambigua, no meramente confusa. En el RFC 3986, la especificación que gobierna las URL, un espacio es %20 y un más es un más literal. Pero los formularios HTML no usan el RFC 3986: usan application/x-www-form-urlencoded, una convención más antigua en la que un espacio se escribe +.
El resultado es que la misma cadena se descodifica de dos formas distintas según quién la lea. decodeURIComponent("a+b") devuelve "a+b", conservando el más. new URLSearchParams("q=a+b").get("q") devuelve "a b", convirtiéndolo en espacio. Ninguna está mal; implementan especificaciones distintas. Por eso una búsqueda de "C++" llega tan a menudo como "C ": algo en la cadena aplicó reglas de formulario a una URL.
En la práctica: dentro de una cadena de consulta, asume que + significa espacio, porque es lo que asumen los navegadores y prácticamente todos los marcos de servidor. En cualquier otro sitio de una URL —un segmento de ruta, un fragmento— un más es un más. La casilla RFC 1738 de esta página cambia la salida a la convención de formulario exactamente por esto.
Por qué descodificar "100%" lanza un error
En una URL codificada, el signo de porcentaje no es un carácter cualquiera: es un marcador de escape, y el descodificador exige exactamente dos dígitos hexadecimales después. Dale a decodeURIComponent la cadena "100%" y no te devolverá "100%"; lanzará URIError: URI malformed, porque después del porcentaje no hay nada que leer.
Esto aflora constantemente con datos reales. Códigos de descuento, estadísticas, cualquier cosa con un porcentaje literal romperá un descodificador a menos que el porcentaje se codificara a su vez como %25 a la ida. Si ves URIError con datos de usuario, el error casi siempre está aguas arriba: algo construyó la URL concatenando cadenas en lugar de codificar cada valor correctamente.
Los caracteres no ASCII se convierten en varios bytes cada uno
La codificación porcentual opera sobre bytes, no sobre caracteres, y las URL modernas llevan UTF-8. Así que un carácter fuera de ASCII se convierte en un escape por byte: é son dos bytes y se codifica como %C3%A9, mientras que un emoji son cuatro bytes y se convierte en doce caracteres de escape.
Conviene recordarlo cuando hay un límite de longitud de por medio. Una ruta o un parámetro que en japonés o árabe parece cómodamente corto puede ser tres veces más largo una vez codificado, y algunos sistemas todavía imponen límites en torno a los 2000 caracteres para la URL entera.
Preguntas frecuentes
¿Se envía mi URL a un servidor?
No. Esta herramienta está marcada como "client": la codificación se ejecuta en la pestaña de tu navegador y el texto nunca sale de tu máquina. Vale la pena señalarlo porque las URL de sistemas reales llevan a menudo tokens de sesión, claves de API o identificadores de clientes en la cadena de consulta; si la tuya lo hace, trátala como una credencial, sea cual sea la herramienta donde la pegues.
¿Debo usar + o %20 para un espacio?
%20 siempre funciona: es válido en cualquier parte de una URL y todos los descodificadores lo entienden. + solo significa espacio dentro de una cadena de consulta, y solo bajo reglas de formulario. Si dudas, usa %20; nunca está mal. Usa + solo cuando produzcas deliberadamente datos de formulario y sepas que quien lee los espera.
Mi URL codificada tiene %2520. ¿Qué ha pasado?
Doble codificación. %25 es un signo de porcentaje codificado, así que %2520 es lo que obtienes cuando %20 pasa por un codificador una segunda vez: el % se convirtió en %25 y el 20 vino detrás. Algo en tu cadena está codificando un valor ya codificado. Codifica exactamente una vez, en el punto donde construyes la URL, y nunca sobre una cadena que no construiste tú.
¿Por qué mi ampersand parte el parámetro en dos?
Porque no se codificó al construir el valor del parámetro. En una cadena de consulta, & es el separador entre parámetros, así que un valor con un & crudo es indistinguible del comienzo de uno nuevo. Tiene que ser %26. Este es además el mecanismo tras la inyección de parámetros, así que conviene arreglarlo bien en el punto donde construyes la URL en vez de parchear el síntoma.
¿Tengo que codificar una URL sacada de la barra de direcciones?
Casi seguro que no: ya está codificada, y volver a codificarla produce el problema del %2520 de arriba. Los navegadores muestran una versión descodificada y legible mientras guardan internamente la codificada. Lo que ves no es lo que se envía. Si una URL ya contiene escapes %, ha sido codificada: descodifícala para leerla, no la codifiques otra vez.