Pré-visualização de Link no Mastodon Não Aparece: Como Corrigir

Quando você compartilha um link em uma postagem do Mastodon, a plataforma geralmente busca metadados da página de destino e exibe um cartão de pré-visualização com título, descrição e imagem. Se esse cartão não aparecer, a postagem parece incompleta e pode reduzir o engajamento dos seguidores. Esse problema geralmente ocorre porque a URL compartilhada não contém as tags Open Graph necessárias, o cache do servidor Mastodon tem dados desatualizados ou a instância bloqueia pré-visualizações de links externos. Este artigo explica as causas raiz das pré-visualizações de link ausentes e fornece correções passo a passo tanto para quem compartilha o link quanto para o administrador da instância Mastodon.

Por que o Mastodon Falha ao Gerar uma Pré-visualização de Link

O Mastodon gera uma pré-visualização de link enviando uma solicitação HTTP em segundo plano para a URL que você cola na caixa de composição. O servidor lê o HTML da página de destino e procura por tags meta específicas definidas pelo protocolo Open Graph. Essas tags incluem og:title, og:description, og:image e og:url. Se a página de destino não incluir essas tags, o Mastodon usa o título HTML e uma descrição genérica como fallback. Se mesmo os dados de fallback estiverem ausentes ou o servidor não conseguir acessar a URL, nenhum cartão de pré-visualização aparece.

A segunda causa comum é o cache do lado do servidor. Depois que o Mastodon busca uma pré-visualização para uma URL, ele armazena esse resultado em cache. Se a página de origem alterar seus metadados posteriormente, a pré-visualização antiga permanece até que o cache expire ou seja limpo manualmente. O tempo de vida padrão do cache é de 24 horas para buscas bem-sucedidas e maior para buscas com falha.

A terceira causa está relacionada às políticas da instância. Alguns administradores de instância Mastodon desativam completamente as pré-visualizações de link para reduzir a carga do servidor ou proteger a privacidade dos usuários. Nesse caso, nenhuma URL gerará um cartão de pré-visualização, independentemente do conteúdo da página de origem.

Passos para Corrigir Pré-visualizações de Link em Suas Próprias Postagens

1. Verifique se a URL está correta e acessível
   Digite ou cole a URL completa em um navegador e confirme se ela carrega sem redirecionamentos ou erros. O Mastodon não segue redirecionamentos JavaScript nem páginas que exigem autenticação.
2. Verifique as tags Open Graph na página de origem
   Abra o código-fonte da página no navegador pressionando Ctrl+U no Windows ou Cmd+U no macOS. Pesquise por og:title. Se encontrar uma linha como <meta property="og:title" content="Título da Sua Página" />, as tags existem. Se estiverem ausentes, o autor da página precisa adicioná-las.
3. Use um encurtador de URL como solução alternativa
   Se você não puder editar a página de origem, cole a URL em um serviço como TinyURL ou Bitly. O Mastodon buscará a pré-visualização do domínio do encurtador, que geralmente inclui tags Open Graph adequadas. Esta é uma correção temporária.
4. Force o Mastodon a buscar novamente a URL
   Na interface web do Mastodon, exclua a URL da caixa de composição e cole-a novamente. Aguarde 10 segundos. Se a pré-visualização não aparecer, o cache ainda contém os dados antigos. Para uma nova busca, adicione um parâmetro de consulta que não afete a página, como ?refresh=1. Exemplo: https://exemplo.com/pagina?refresh=1.
5. Teste com uma URL conhecida que funciona
   Cole uma URL de um grande site de notícias, como https://www.bbc.com/news. Se essa URL gerar uma pré-visualização, o problema está na URL original. Se não, o problema está no lado da instância Mastodon.

Passos para Administradores Restaurarem Pré-visualizações de Link

Se vários usuários em sua instância relatarem pré-visualizações ausentes para várias URLs, o problema provavelmente se origina da configuração do servidor ou do cache. Os passos a seguir exigem acesso shell ao servidor Mastodon e familiaridade com o console Rails.

1. Verifique a configuração de pré-visualização de link no painel de administração
   Faça login como administrador. Vá para Preferências > Administração > Configurações do Servidor > Retenção de conteúdo. Certifique-se de que a opção “Ativar pré-visualizações de link” esteja marcada. Se estiver desmarcada, marque-a e clique em Salvar.
2. Limpe o cache de cartões de pré-visualização via console Rails
   Conecte-se via SSH ao seu servidor. Execute cd /home/mastodon/live e depois RAILS_ENV=production bundle exec rails c. No console, digite PreviewCard.where.not(url: nil).delete_all. Isso remove todos os cartões de pré-visualização em cache. Saia com exit. O Mastodon buscará novas pré-visualizações na próxima postagem que contiver uma URL.
3. Verifique se o worker sidekiq está em execução
   A busca de pré-visualização de link é feita pela fila sidekiq LinkCrawlWorker. Execute sudo systemctl status mastodon-sidekiq. Se o serviço estiver inativo, reinicie-o com sudo systemctl restart mastodon-sidekiq.
4. Verifique o firewall da instância e o DNS
   O Mastodon precisa conseguir fazer solicitações HTTPS de saída. Execute curl -I https://exemplo.com a partir do servidor. Se o comando expirar, o servidor não consegue acessar URLs externas. Atualize as regras do firewall para permitir tráfego de saída na porta 443.

Se as Pré-visualizações de Link Ainda Não Aparecerem

O cartão de pré-visualização mostra apenas o nome do domínio, sem imagem

Isso acontece quando a página de origem tem og:title, mas não tem og:image ou usa uma imagem muito pequena. O Mastodon exige que a imagem tenha pelo menos 200 por 200 pixels. O autor da página deve adicionar uma tag og:image maior.

A pré-visualização aparece na interface web, mas não nos aplicativos

Alguns aplicativos Mastodon de terceiros não renderizam cartões de pré-visualização. Teste a mesma postagem na interface web oficial do Mastodon. Se a pré-visualização aparecer lá, o aplicativo é o fator limitante. Atualize o aplicativo ou entre em contato com o desenvolvedor.

O cartão de pré-visualização mostra informações desatualizadas

O servidor Mastodon armazenou em cache a pré-visualização antes da página de origem atualizar seus metadados. O administrador deve limpar o cache conforme descrito na seção anterior. Para uma única URL, o usuário pode adicionar um parâmetro de consulta para forçar uma nova busca.

Pré-visualização de Link do Mastodon vs. Pré-visualização de Card do Twitter

Item	Pré-visualização de Link do Mastodon	Pré-visualização de Card do Twitter
Formato dos metadados	Open Graph (tags og:)	Twitter Card (tags twitter:)
Comportamento de fallback	Usa a tag title do HTML e a meta description	Usa a tag title do HTML e a meta description
Tamanho mínimo da imagem	Mínimo 200×200 pixels	Mínimo 120×120 pixels
Duração do cache	24 horas para buscas bem-sucedidas	7 dias para buscas bem-sucedidas
Controle do administrador	Pode desativar pré-visualizações ou limpar cache	Nenhum controle direto em terceiros

O Mastodon depende exclusivamente de tags Open Graph, enquanto o Twitter também suporta suas próprias tags de card. Se uma página segmenta apenas tags Twitter Card, o Mastodon não gerará uma pré-visualização. Autores de páginas devem incluir tags og: e twitter: para máxima compatibilidade.

Conclusão

Agora você pode diagnosticar e corrigir pré-visualizações de link ausentes no Mastodon verificando as tags Open Graph na página de origem, adicionando um parâmetro de consulta para ignorar o cache ou ajustando as configurações do servidor. Se você é administrador de uma instância, lembre-se de limpar a tabela PreviewCard no console Rails e verificar se a fila sidekiq LinkCrawlWorker está ativa. Para uma solução de longo prazo, incentive os criadores de conteúdo a incluir as tags og:title, og:description e og:image em suas páginas. Isso garante que as pré-visualizações funcionem no Mastodon e em outras plataformas que seguem o padrão Open Graph.