Verificação HTML: Valor inválido para o atributo "src" no elemento "img": Carácter ilegal na consulta: "[" não é permitido.

Sobre este problema HTML

A especificação de URL (definida pela WHATWG e RFC 3986) restringe quais caracteres podem aparecer não codificados em diferentes partes de uma URL. Os parênteses retos são caracteres reservados que têm um significado específico em URLs — só são permitidos na porção do host (para envolver endereços IPv6 como [::1]). Na string de consulta, devem ser codificados por percentagem.

Este problema aparece comumente quando frameworks (especialmente PHP, Ruby on Rails, ou bibliotecas JavaScript) geram URLs com parâmetros de consulta no estilo de array como ?filter[color]=red. Embora muitos navegadores e servidores sejam permissivos e interpretem estas URLs corretamente, são tecnicamente inválidas de acordo com o padrão de URL. O validador W3C impõe esta regra rigorosamente.

Além da conformidade com padrões, usar parênteses retos não codificados pode causar problemas na prática. Alguns clientes HTTP, proxies, ou camadas de cache podem rejeitar ou corromper URLs contendo parênteses retos. A codificação por percentagem destes caracteres assegura que as suas URLs são universalmente seguras e interoperáveis em todos os sistemas.

Como corrigir

Você tem duas abordagens principais:

Codifique por percentagem os parênteses retos. Substitua cada [ por %5B e cada ] por %5D na URL. Isto preserva a estrutura de parâmetros que o seu servidor ou framework espera, enquanto torna a URL válida.
Reestruture os parâmetros de consulta. Se o seu backend permitir, use nomes de parâmetros simples com notação de ponto, underscores, ou hífens em vez de sintaxe de parênteses retos. Por exemplo, mude size[width] para size_width ou size.width.

Se estiver a gerar URLs em JavaScript, a função integrada encodeURI() não codifica parênteses retos. Use encodeURIComponent() em nomes ou valores de parâmetros individuais, ou substitua manualmente [ e ] após construir a URL.

Exemplos

❌ Inválido: parênteses retos não codificados na string de consulta

<img src="/images/photo.jpg?size[width]=300&size[height]=200" alt="A sample photo">

Os caracteres literais [ e ] na string de consulta desencadeiam o erro de validação.

✅ Corrigido: parênteses retos codificados por percentagem

<img src="/images/photo.jpg?size%5Bwidth%5D=300&size%5Bheight%5D=200" alt="A sample photo">

Substituir [ por %5B e ] por %5D torna a URL válida. A maioria dos servidores e frameworks descodificará estes automaticamente e interpretará os parâmetros da mesma forma.

✅ Corrigido: nomes de parâmetros simples sem parênteses retos

<img src="/images/photo.jpg?size_width=300&size_height=200" alt="A sample photo">

Se você controlar a lógica do lado do servidor, pode evitar parênteses retos completamente usando uma convenção de nomenclatura simples para os seus parâmetros.

❌ Inválido: parênteses retos em strings de consulta mais complexas

<img
  src="/api/image?filters[type]=jpeg&filters[quality]=80&crop[x]=10&crop[y]=20"
  alt="Processed image">

✅ Corrigido: todos os parênteses retos codificados

<img
  src="/api/image?filters%5Btype%5D=jpeg&filters%5Bquality%5D=80&crop%5Bx%5D=10&crop%5By%5D=20"
  alt="Processed image">

Codificação em JavaScript

Se você construir URLs de imagem dinamicamente, trate a codificação no seu código:

// Abordagem de substituição manual
const url = "/images/photo.jpg?size[width]=300&size[height]=200";
const safeUrl = url.replace(/\[/g, "%5B").replace(/\]/g, "%5D");
img.src = safeUrl;

// Usando URLSearchParams (codifica parênteses retos automaticamente)
const params = new URLSearchParams();
params.set("size[width]", "300");
params.set("size[height]", "200");
img.src = `/images/photo.jpg?${params.toString()}`;

Ambas as abordagens produzem uma URL válida e adequadamente codificada que passará na validação W3C.