Ferramentas de desenvolvedor · Codificador e decodificador URL
URIError: URI malformado — por que decodeURIComponent é lançado e como corrigi-lo
· Como funciona
codificação de URL javascript tratamento de erros
decodeURIComponent é lançado quando um sinal de porcentagem não é seguido por dois dígitos hexadecimais ou quando os bytes decodificados não são UTF-8 válidos. Esta postagem mostra as entradas que o acionam e como decodificar defensivamente.
O sinal de porcentagem que travou - por que "100% off" quebra o decodeURIComponent
Um formulário coleta o código de desconto "100% off". JavaScript passa isso para decodeURIComponent em um decodificador URL. A função lança URIError: URI malformado. O sinal de porcentagem não é seguido por dois dígitos hexadecimais. Isso viola completamente as regras de codificação percentual. decodeURIComponent espera que cada % inicie um trio como %20 ou %C3. Um% solitário é um erro de sintaxe que interrompe a execução imediatamente e gera um erro.
Capturar esse erro evita totalmente travamentos do aplicativo com segurança. Os URLs chegam a partir de entradas do usuário, redirecionamentos, códigos QR e e-mails. Erros de digitação acontecem com frequência. Um relatório de falha com URIError informa onde investigar rapidamente. A decodificação defensiva mantém os aplicativos em execução e os logs de erros tornam-se úteis para depuração.
Dois tipos de falha - escapes hexadecimais malformados e sequências de bytes UTF-8 inválidas
decodeURIComponent é lançado exatamente em duas situações. Primeiro: sequência de escape malformada. Uma porcentagem não seguida por dois dígitos hexadecimais (0-9, A-F, a-f). Exemplos: %ZZ, %2, %2g. Segundo: tripleto válido como %E9 decodificação para bytes UTF-8 inválidos. O primeiro é o erro de formato. O segundo é o erro semântico. Ambos lançam e param a execução imediatamente.
UTF-8 possui regras rígidas sobre sequências de bytes. Os bytes 0x80–0xFF aparecem apenas em sequências de vários bytes. Um único %E9 não pode ser UTF-8 válido sozinho. Este byte órfão aciona um erro. Erros de formato são óbvios. Os erros semânticos são sutis, mas igualmente reais. Ambos os casos requerem manipulação try/catch no código de produção.
Codificação herdada de byte único - quando %E9 sozinho é lançado, mas %C3%A9 sobrevive
A confusão decorre da história dos padrões da web. As páginas antigas usavam Latin-1 em vez de UTF-8. Em latim-1, %E9 representado é. Os navegadores modernos usam exclusivamente UTF-8. UTF-8 codifica é como %C3%A9. Os decodificadores modernos esperam UTF-8 e rejeitam %E9 como malformado. Este é o comportamento correto. O erro sinaliza um problema com os dados de origem.
Consenso moderno: UTF-8 em todos os lugares. O padrão URL especifica UTF-8. Todos os navegadores atuais usam UTF-8. Se você encontrar %E9 de sistemas antigos, detecte o erro e retorne à string bruta. Não decodifique como Latin-1 no código moderno. Investigue a origem dos dados.
Três entradas, três mensagens de erro — como os motores diferem na mesma string quebrada
Os mecanismos do navegador rejeitam entradas malformadas de forma consistente, mas erros de palavras de maneira diferente. O Chrome relata "URI malformado". O Firefox relata "sequência URI malformada". Os relatórios do Safari "não podem converter indefinido em objeto". Todos os três motores rejeitam entradas idênticas. O texto exato da mensagem não é padronizado em diferentes mecanismos ou versões. Nunca confie no texto do erro para orientar a lógica do código.
Nunca corresponda uma mensagem de erro para decisões de programa. Sempre capture URIError por tipo. A função decodeUrl agrupa decodeURIComponent e fornece código consistente INVALID_PERCENT_ENCODING. Isso nomeia a posição exata do problema. Funciona em tempos de execução porque não depende de variações de palavras do mecanismo. Essa abordagem é mais confiável e sustentável.
Lendo a exceção com segurança – validação try/catch, e padrões de fallback
Padrão defensivo mais simples: envolva decodeURIComponent em try/catch. Se for lançado, use string bruta ou caractere de substituição. Isso evita que entradas malformadas travem. Para valores de consulta, mostre o formulário codificado em URL. Para texto voltado ao usuário, insira um caractere de substituição. Isso evita que entradas incorretas interrompam os aplicativos e mantém a estabilidade.
Pré-valide com expressões regulares para velocidade e segurança. Verifique se a entrada contém apenas trigêmeos %XX válidos antes da decodificação. O padrão /%[0-9A-Fa-f]{2}/g captura escapes válidos; qualquer coisa sem correspondência é inválida. Erros de formato falham rapidamente em lixo óbvio. UTF-8 erros ainda precisam de try/catch. Juntos, isso fornece proteção defensiva abrangente contra erros.
Falhas silenciosas escondem bugs – por que a decodificação cega é tão arriscada quanto a codificação quebrada
Risco sutil: o decodificador não lança, mas produz silenciosamente o texto errado. Código antigo usando unescape obsoleto deixa UTF-8 inválido na memória. O texto parece bom na tela até chegar a sistemas que validam UTF-8 estritamente. O código moderno é lançado em vez de corrompido silenciosamente. Uma exceção é mais clara e segura do que a corrupção silenciosa de dados que se espalha a jusante.
Suponha que a entrada do usuário esteja malformada. Sempre encerre as chamadas. Registre erros com entrada original para depuração. Nunca presuma que cada% é válido. Erros de digitação e truncamento criam escapes incompletos. Trate como erros de dados, não como erros lógicos. O código defensivo sobrevive a entradas incorretas normalmente e mantém os sistemas confiáveis.
O que as ferramentas reais ignoram – comportamento da estrutura do lado do servidor e recuperação de erros
As estruturas de servidor lidam com codificação malformada de maneira mais tolerante do que os navegadores. Ruby, Python e PHP oferecem configuração para lidar com escapes inválidos em URLs. Alguns substituem caracteres de substituição automaticamente. Outros descartam bytes silenciosamente. Alguns lançam exceções como JavaScript faz. O comportamento real varia de acordo com a estrutura e as configurações escolhidas pelos desenvolvedores.
Este artigo aborda apenas o comportamento JavaScript do navegador. Se os valores chegarem das APIs do servidor, o servidor já decodificou ou ignorou erros antes do envio. Os servidores podem ser mais indulgentes do que os clientes. Ao escrever contratos API, especifique se os valores são brutos ou pré-decodificados. URL strings de consulta devem chegar codificadas em porcentagem; JSON pode chegar pré-decodificado.
Valide antecipadamente - usando o codificador e decodificador URL para verificar primeiro as strings suspeitas
Antes de passar URLs suspeitos para decodeURIComponent, cole no codificador e decodificador URL. A ferramenta mostra a codificação exata, detecta escapes malformados e explica erros sem travar seu aplicativo. Teste com %ZZ, %E9 e 100% para ver diferentes falhas e suas mensagens de erro exatas. Isso leva segundos e aumenta a confiança.
Valide antecipadamente, detecte erros normalmente e registre o que quebrou. O decodificador defensivo e a ferramenta de teste mantêm os aplicativos em execução e depuráveis. O codificador e decodificador URL transforma "URI malformado" em informações acionáveis que você pode usar imediatamente. Aplique esse padrão aos seus próprios decodificadores para obter resiliência e capacidade de manutenção em ambientes de produção.