SVG não está renderizando no navegador? Causas Comuns
Por que seu SVG mostra um ícone de imagem quebrada (ou nada)
Arquivos SVG deveriam ser fáceis. Como uma alternativa infinitamente escalável aos formatos raster, eles geralmente são confiáveis. Mas quando um SVG se recusa a renderizar, a falha é frequentemente silenciosa e confusa. Você vê um ícone de imagem quebrada, um retângulo branco em branco ou apenas um espaço vazio onde seu gráfico deveria estar. Um JPEG corrompido, pelo menos, parece obviamente quebrado; um SVG ruim pode parecer perfeito em um editor de texto e ainda assim não mostrar nada no Chrome, Firefox ou Safari. Os problemas geralmente se resumem a algumas questões distintas: um tipo MIME incorreto do servidor web, XML malformado dentro do arquivo, políticas de segurança bloqueando código inline, ou problemas de dimensionamento que renderizam o SVG com tamanho visível zero. Cada um tem uma solução diferente, e confundi-los fará você perder horas. Este guia detalha cada causa com as configurações e atributos específicos que você precisa verificar, não apenas conselhos vagos para 'validar seu arquivo'. Uma distinção importante antes de começarmos: alguns problemas de SVG começam na ferramenta de design (Illustrator, Figma) durante a exportação, enquanto outros acontecem durante a conversão do arquivo. Se você usou uma ferramenta online para converter um arquivo para SVG e ele quebrou, isso é uma classe diferente de problema do que um SVG perfeito que seu servidor está configurando incorretamente. Vamos nos certificar de distinguir entre os dois.
Tipo MIME incorreto: O problema do lado do servidor que a maioria dos desenvolvedores ignora
Quando você usa uma tag `<img>` ou `background-image` do CSS para exibir um SVG, o navegador inspeciona o cabeçalho Content-Type enviado pelo servidor. Se esse cabeçalho ler `text/plain` ou `application/octet-stream` em vez do correto `image/svg+xml`, a maioria dos navegadores simplesmente se recusará a renderizar a imagem. O arquivo em si pode estar impecável. Esta é uma das causas mais comuns de SVGs quebrados em produção, e é um fantasma no desenvolvimento local. Por quê? Porque localmente, você provavelmente está apenas abrindo o arquivo do disco, não o servindo. O problema só aparece depois que você faz o deploy. Para diagnosticar isso, abra as Ferramentas do Desenvolvedor do seu navegador (F12), mude para a aba Rede (Network) e recarregue a página. Encontre seu SVG na lista de requisições, clique nele e olhe os Cabeçalhos de Resposta (Response Headers). A linha `Content-Type` deve dizer `image/svg+xml`. Se disser qualquer outra coisa, você encontrou seu problema. A correção está no servidor, não no arquivo. No Apache, você pode corrigir isso adicionando `AddType image/svg+xml .svg .svgz` ao seu arquivo `.htaccess`. Para usuários do Nginx, adicione `image/svg+xml svg svgz;` dentro do bloco `types` do seu `nginx.conf`. Se você estiver no IIS, precisará usar o Internet Information Services Manager para adicionar um mapeamento de tipo MIME para a extensão `.svg` para `image/svg+xml`. Se você estiver usando uma plataforma gerenciada como Netlify ou Vercel, isso é tratado em um arquivo de configuração (`netlify.toml` ou `vercel.json`). A sintaxe do Netlify, por exemplo, usa um bloco `[[headers]]` para definir o `Content-Type` para um determinado caminho. É uma correção de cinco minutos que pode economizar horas de frustração, mas apenas se você souber onde procurar no painel de rede.
XML malformado: Quando o próprio arquivo SVG é o problema
Um SVG é um documento XML, o que significa que segue regras de parsing rigorosas. Uma tag de fechamento ausente, um 'e comercial' não escapado ou um `id` duplicado pode fazer com que o arquivo inteiro falhe silenciosamente em alguns navegadores. Aqui vai uma dica: se o seu SVG renderiza no Chrome, mas não no Firefox, XML malformado é o principal suspeito. O Firefox é muito mais explícito sobre erros de XML. Para ver por si mesmo, arraste o arquivo SVG diretamente para uma janela do Firefox. Se o XML estiver quebrado, o Firefox mostrará uma mensagem de erro clara, completa com número de linha e coluna: 'XML Parsing Error: not well-formed at line 47, column 12.' Esse é o seu mapa do tesouro. Abra o arquivo em um editor de texto como o VS Code e vá para aquele local exato. O que você está procurando? Muitas vezes é um 'e comercial' (`&`) em um link que deveria ter sido escrito como `&`. Ou você pode encontrar um elemento `<path>` ou `<g>` não fechado. Problemas de codificação são outro clássico, onde uma ferramenta de design exporta caracteres fora do intervalo ASCII padrão sem declarar UTF-8. Seu arquivo SVG deve sempre começar com `<?xml version="1.0" encoding="UTF-8"?>` se contiver quaisquer caracteres não-ASCII. Versões mais antigas do Adobe Illustrator adoravam exportar arquivos com namespaces XML proprietários. Embora não seja tecnicamente inválido, isso adiciona peso inútil e às vezes pode confundir os parsers. Executar esses arquivos através de um otimizador como o SVGO geralmente remove esses namespaces, o que é bom. O perigo é se a aparência do gráfico dependia de alguma forma desses atributos proprietários, caso em que a limpeza do arquivo pode quebrá-lo inesperadamente. Se você converteu um arquivo para SVG usando o CocoConvert e a saída tem erros de XML, por favor, nos avise através do botão de feedback na página de resultados. Nós ativamente rastreamos e corrigimos esses tipos de artefatos de conversão.
Conflitos de SVG Inline e Content Security Policy
Colar a marcação SVG diretamente no seu HTML é uma técnica poderosa, mas vem com uma grande ressalva: o SVG se torna parte do DOM. Isso significa que agora está sujeito à Content Security Policy (CSP) da sua página. Uma CSP estrita pode desativar silenciosamente partes do seu SVG, levando à confusão. Isso é especialmente verdadeiro para SVGs contendo elementos `<script>`, blocos `<style>` para animações, ou elementos `<use>` que referenciam definições de símbolos externos. Uma diretiva CSP comum como `script-src 'self'` bloqueará a execução de quaisquer scripts inline dentro do seu SVG. Uma diretiva como `img-src 'self'` pode impedir que o SVG carregue uma imagem externa referenciada via `<image href="https://external-domain.com/...">`. A boa notícia? O navegador dirá exatamente o que está errado. Abra o console do desenvolvedor do navegador (a aba Console, não Rede) e procure por mensagens de erro em vermelho. Violações de CSP são muito explícitas, indicando qual recurso foi bloqueado e qual diretiva de política foi responsável, como: 'Refused to load the script because it violates the following Content Security Policy directive: script-src self.' Como você corrige isso depende das necessidades do seu SVG. Você poderia adicionar `'unsafe-inline'` à sua diretiva `style-src`, mas isso enfraquece sua política de segurança, então eu desaconselho fortemente. Uma solução muito melhor para SVGs animados é mover o CSS para uma folha de estilo externa e vinculá-la com `<?xml-stylesheet type="text/css" href="styles.css"?>`. Para elementos `<use>` apontando para arquivos externos, você precisará inlinear os símbolos ou ajustar sua política `img-src` para incluir a origem na lista de permissões. SVGs gerados pelo CocoConvert ou ferramentas semelhantes não terão scripts, então você não verá conflitos de `script-src` com eles. No entanto, conflitos de `style-src` ainda são possíveis se o SVG convertido usar CSS inline para cores ou fontes.
Configurações incorretas de Viewport e ViewBox que tornam o SVG invisível
Este é o tipo mais irritante de problema com SVG. O navegador está renderizando o SVG perfeitamente, mas ele está sendo renderizado com tamanho zero ou em algum lugar fora da tela. Você não vê um ícone de imagem quebrada; você não vê nada. Qualquer um que já olhou para um espaço em branco no DevTools, vendo o elemento `<svg>` bem ali, mas nada na tela, conhece essa dor particular. A chave é a relação entre o atributo `viewBox`, que define o sistema de coordenadas interno do gráfico, e os atributos `width` e `height`, que definem quanto espaço o SVG ocupa na página. Quando estão ausentes ou desalinhados, o caos se instala. Você verá isso frequentemente com exportações do Figma: um SVG recebe `width="100%"` e `height="100%"`, mas não tem `viewBox`. Se você colocar esse SVG em um contêiner que não possui uma altura explícita, o SVG colapsa para altura zero. A correção é adicionar um `viewBox` que corresponda às dimensões originais da prancheta (por exemplo, `viewBox="0 0 800 600"`) ou dar ao elemento contêiner uma altura no seu CSS. Outro clássico é um SVG onde os dados do caminho são desenhados em coordenadas muito fora do `viewBox`. Se o seu `viewBox` é `"0 0 100 100"`, mas seus dados de caminho começam em `M 500 500`, o gráfico está sendo desenhado 400 unidades fora da tela. Isso acontece quando você move formas em uma ferramenta de design sem redefinir a origem da prancheta. Para corrigir, volte à sua ferramenta de design, selecione todos os objetos e use um comando 'Reset Bounding Box' ou seu equivalente, então re-exporte. Para diagnosticar isso, inspecione o SVG no DevTools. Se sua largura ou altura computada for 0, o dimensionamento é o culpado. Você também pode forçar o problema adicionando temporariamente `style="border: 1px solid red; width: 200px; height: 200px;"` diretamente à tag `<svg>`. Isso criará uma caixa visível e revelará se alguma parte do seu gráfico está aparecendo.
Falhas de carregamento de fontes e recursos externos dentro do SVG
Um SVG nem sempre é autocontido. Ele pode referenciar recursos externos como fontes, imagens, gradientes e filtros. Quando essas chamadas externas falham, o SVG pode renderizar parcialmente ou parecer completamente errado, dependendo de quão crítica é a peça que falta. Falhas de fontes são uma dor de cabeça frequente. Um SVG que especifica uma fonte personalizada em um elemento `<text>` usará uma fonte padrão do sistema se essa fonte não estiver disponível. Isso geralmente não quebra a renderização por completo, mas pode fazer com que o texto transborde seu contêiner e desorganize todo o layout. Meu conselho: sempre converta o texto para contornos (paths) antes de exportar um SVG para uso na web. No Illustrator, é Tipo > Criar Contornos; no Inkscape, é Caminho > Objeto para Caminho. Isso elimina completamente a dependência de fontes e uma classe inteira de problemas. Imagens externas dentro de um SVG são ainda mais delicadas. Uma tag `<image>` apontando para uma URL pode falhar porque a URL está fora do ar, porque o servidor de imagens não possui cabeçalhos CORS adequados, ou porque uma CSP bloqueia a origem. O navegador não mostrará um ícone de erro; ele apenas renderizará um espaço em branco onde a imagem deveria estar. Verifique sua aba Rede (Network) para requisições com status 404 ou status 0, o que frequentemente indica um bloqueio de CORS ou CSP. Se você estiver convertendo um arquivo PDF ou AI que contém imagens raster, o CocoConvert irá incorporar essas imagens diretamente no SVG como URIs de dados base64. Isso resolve o problema de referência externa, mas pode tornar o arquivo SVG enorme. Um PDF com algumas fotos pode facilmente se tornar um SVG de 5MB+. Nesses casos, vamos dizer claramente: converter para PNG ou WebP é a escolha mais prática. Não vamos fingir que SVG é sempre a resposta certa.
Quando a conversão é a origem do problema (e o que fazer a respeito)
Às vezes, o problema não é o seu navegador ou o seu servidor. O próprio arquivo SVG estava quebrado desde o início, uma vítima de um processo de conversão ruim. É importante reconhecer essa possibilidade, porque isso significa que você deve parar de depurar seu ambiente e começar a analisar o arquivo. Artefatos de conversão comuns incluem dados de caminho com precisão absurdamente alta (mais de 15 casas decimais), o que incha os arquivos e pode causar timeout nos parsers; conversões incorretas de espaço de cores de CMYK para valores RGB não suportados; e codificação de texto quebrada se um arquivo de origem usou scripts não latinos. Você também pode ver declarações de namespace ausentes ao converter de formatos que dependem de XML proprietário. Se você suspeita de uma conversão ruim, a maneira mais rápida de verificar é abrir o SVG no Inkscape. É gratuito, multiplataforma e possui um parser SVG muito tolerante. Se o arquivo parece correto no Inkscape, mas está quebrado no Chrome, o problema é provavelmente específico do navegador. Se estiver quebrado no Inkscape também, então o próprio processo de conversão falhou e a saída está corrompida. O CocoConvert usa bibliotecas de conversão robustas, mas nenhuma ferramenta automatizada é perfeita. Um arquivo AI altamente complexo com centenas de camadas, ou um PDF que depende muito de efeitos de transparência, pode produzir uma saída SVG imperfeita. Nessas situações, o caminho mais confiável é muitas vezes abrir o arquivo de origem em seu aplicativo original, exportar diretamente para SVG, e usar o CocoConvert para pares de formatos em que somos excelentes, como converter PNGs simples para SVG ou SVG para PDF para impressão. Se você receber um SVG quebrado de uma conversão, por favor, denuncie usando o formulário de feedback na página de resultados, e inclua o arquivo original se puder. Exemplos específicos são como melhoramos o pipeline de conversão para todos, e levamos esses relatórios a sério.