Cómo corregir UTF-8 mal codificado con porcentajes
Un valor de una URL llega a su aplicación, pero decodeURIComponent() lanza URIError. Antes de sustituir signos de puntuación, distinga dos fallos: un escape de porcentaje incompleto y un escape de bytes completo que no forma UTF-8 válido.
Localice el punto en el que cambia el valor
Suponga que un cuadro de búsqueda acepta 50% off, pero abrir el enlace generado hace fallar la página. El porcentaje es texto normal en el buscador. Solo adquiere un significado especial cuando el código trata ese texto como un componente de URL ya codificado. Anote el valor esperado en cada paso: el texto del usuario, la URL serializada y el valor leído por la página receptora. Está buscando una incompatibilidad de codificación, no signos que borrar.
Utilice un ejemplo inocuo en lugar de copiar un enlace real de recuperación de contraseña o una consulta de cliente en una consola o incidencia pública. Pruebe primero decodeURIComponent("%25"); el resultado esperado es un único porcentaje. Después pruebe el ejemplo que falla con la función protegida del apartado «Rechace entradas mal formadas sin detener la página». Si el ejemplo válido funciona y el otro falla, el decodificador no está roto en todos los casos: hay que investigar los datos recibidos.
Distinga un escape incompleto de bytes UTF-8 no válidos
Un % aislado carece de un valor de byte de dos dígitos. En cambio, %92 sí tiene sintaxis de escape de byte, pero ese byte no puede aparecer solo en UTF-8. Las consultas públicas muestran ambos errores, incluidos bytes de comillas de codificaciones antiguas y un %AF aislado.
decodeURIComponent("%"); // URIError
decodeURIComponent("%92"); // URIError
decodeURIComponent("%25"); // %
decodeURIComponent("%C2%AF"); // ¯
decodeURIComponent("%E2%80%99"); // ’
El ejemplo conservado de Node v24.19.0 reprodujo estos resultados y también probó %91, %AF y la comilla izquierda UTF-8. El mensaje del navegador puede variar; la evidencia útil es si la entrada exacta se acepta o se rechaza.
Construya las consultas sin concatenar escapes manualmente
Para crear un enlace, pase el texto original a la API URL y deje que serialice el parámetro. En el receptor, lea ese parámetro con la misma API. No vuelva a decodificar inmediatamente el valor devuelto:
const link = new URL("https://example.com/search");
link.searchParams.set("q", "50% off & café");
const received = new URL(link.href).searchParams.get("q");
console.log(received); // 50% off & café
Es una URL de ejemplo, no un endpoint de FrAIFlow. Lo importante es distinguir un componente codificado de un valor que ya se ha interpretado. Una segunda decodificación puede convertir texto perfectamente válido como 50% off en una excepción. Recuerde también que el signo más recibe un tratamiento diferente en parámetros de consulta de formularios que cuando se pasa literalmente a decodeURIComponent(); utilice el analizador adecuado para el formato.
Corrija el origen en lugar de adivinar caracteres
Conserve en privado la muestra exacta que falla y pregunte al emisor qué codificación utilizó. Un %92 aislado puede sugerir una codificación antigua, pero el byte por sí solo no demuestra su origen. No lo sustituya silenciosamente por un apóstrofo en identificadores de cuenta, firmas o nombres de archivo. Devuelva un error útil, preserve la entrada original del usuario y corrija la codificación en el origen cuando sea posible.
Después del cambio, pruebe un porcentaje literal, una palabra acentuada, una comilla tipográfica, un signo más y un ampersand. Cada valor debe recorrer crear enlace → abrir enlace → leer valor sin cambiar. Una entrada mal formada debe producir un error controlado, no detener el resto de la página. Estas comprobaciones verifican el formato acordado; no justifican decodificar repetidamente hasta que una cadena parezca legible.
Rechace entradas mal formadas sin detener la página
function decodeComponent(value) {
try { return { ok: true, value: decodeURIComponent(value) }; }
catch (error) {
if (!(error instanceof URIError)) throw error;
return { ok: false, error: "Invalid encoded component" };
}
}
Esta función comunica el fallo sin cambiar silenciosamente un identificador. No puede descubrir una codificación de origen desconocida. Decodifique solo las veces previstas por el formato: que quede un porcentaje después de una decodificación correcta no justifica otra pasada. Evite el obsoleto unescape() como arreglo de UTF-8 y no incluya tokens ni valores privados de consultas en registros públicos de diagnóstico.
