Como integrar comentários em um blog Astro: guia completo de Giscus, Waline e Twikoo

Levei bastante tempo para decidir como adicionar comentários ao meu blog Astro.

No começo, parecia simples: bastava incorporar algum sistema de comentários. Quando coloquei a mão na massa, porém, descobri opções demais — Giscus, Waline, Twikoo, Disqus… Todas prometem facilidade, mas cada uma tem uma configuração completamente diferente. E ainda havia uma armadilha: depois de seguir um tutorial e deixar tudo funcionando, eu abria o blog e os comentários apareciam normalmente. A alegria durava dois segundos. Bastava navegar para outro artigo e eles desapareciam.

Mais tarde descobri que o culpado era o roteamento com transições de visualização do Astro, o View Transitions. Na troca de página, o componente de comentários não era recarregado e virava uma espécie de “comentário de Schrödinger”: só dava para saber se apareceria depois de clicar.

Se você enfrentou algo parecido ou ainda está tentando escolher um sistema de comentários, este artigo pode ajudar. Vou comparar três opções populares — Giscus, Waline e Twikoo —, mostrar o código completo de integração com Astro e resolver a compatibilidade com View Transitions. Ao terminar, você poderá colocar tudo em funcionamento em 10 minutos.

Comparativo de sistemas de comentários: qual escolher?

Para ser sincero, testei os três sistemas, e cada um tem vantagens e desvantagens. Primeiro, veja uma comparação direta:

Minha recomendação

Mesmo depois da tabela, a escolha talvez ainda não pareça óbvia. Então vamos ser mais específicos.

Se o seu blog é voltado principalmente para programadores, como um site de tutoriais técnicos ou de documentação de projetos de código aberto, escolha o Giscus. O motivo é simples: seus leitores provavelmente já têm uma conta no GitHub, então entrar com ela para comentar acaba sendo mais conveniente. Além disso, Giscus é uma solução apenas de frontend, não exige backend e fica pronto em 5 minutos.

Se o seu blog é voltado para o público geral, com relatos do cotidiano, fotografia ou viagens, escolha Waline ou Twikoo. Ambos aceitam comentários anônimos, o que reduz a barreira de participação: não é preciso se cadastrar nem entrar em uma conta; basta informar nome e e-mail. O painel administrativo do Waline é mais robusto e atende melhor blogs com muitos comentários, enquanto o Twikoo é mais leve e um pouco mais simples de implantar.

Se, como eu, você quer custo zero, escolha o Giscus sem pensar duas vezes. Ele depende exclusivamente dos serviços gratuitos do GitHub: não exige banco de dados adicional, serviço de nuvem pago nem sequer o aluguel de um servidor. Waline também tem uma franquia gratuita — 1 GB no plano de desenvolvimento do LeanCloud —, mas um blog com muito tráfego talvez precise migrar para um plano pago.

Se você precisa de um painel administrativo robusto para moderar comentários, consultar estatísticas e filtrar spam, escolha o Waline. O painel dedicado permite processar comentários em lote e consultar estatísticas de acesso, com uma experiência parecida com a de um plugin de comentários do WordPress.

Em resumo: Giscus para blogs de tecnologia, Waline para blogs sobre cotidiano e Twikoo para quem busca simplicidade máxima.

Como integrar o Giscus: a opção mais simples

Giscus é o sistema de comentários que mais recomendo, sobretudo para blogs de tecnologia. Entre as três opções, é o mais simples de configurar: não exige backend nem banco de dados e funciona inteiramente com os serviços gratuitos do GitHub.

Preparação

Antes de integrar o Giscus, conclua estas etapas:

1. Crie um repositório público no GitHub

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Você pode usar o próprio repositório do código-fonte do blog ou criar outro só para armazenar os comentários, com um nome como blog-comments. O repositório precisa ser público; os comentários não aparecem se ele for privado.

2. Ative o recurso Discussions

Abra a página Settings do repositório, role até a seção Features e marque Discussions. O recurso vem desativado por padrão e precisa ser habilitado manualmente.

3. Instale o aplicativo giscus

Acesse https://github.com/apps/giscus, clique em Install e selecione o repositório que acabou de preparar. Essa etapa autoriza o bot do giscus a acessar o repositório para criar e gerenciar Discussions automaticamente.

4. Configure uma categoria de Discussion

Abra a página Discussions do repositório e clique na configuração de Categories, no canto superior direito. Recomendo criar uma categoria do tipo Announcements, com um nome como “Comments”. Assim, somente você e o bot do giscus poderão criar tópicos; os demais usuários poderão apenas responder, o que ajuda a evitar spam.

Obtenha os parâmetros de configuração

Depois da preparação, acesse https://giscus.app/zh-CN e preencha os dados solicitados:

1. Nome do repositório: informe seu-usuario/nome-do-repositorio, como zhangsan/blog-comments
2. Mapeamento entre página e Discussion: recomendo pathname, para que cada página crie automaticamente uma Discussion com base no caminho da URL
3. Categoria da Discussion: escolha a categoria do tipo Announcements que você criou
4. Tema: escolha light ou dark; você também pode usar preferred_color_scheme para acompanhar o sistema

Ao terminar, a parte inferior da página vai gerar um trecho de configuração com parâmetros como data-repo, data-repo-id e data-category-id. Anote esses valores, pois você vai usá-los em seguida.

Código de integração com Astro

Agora vem a parte principal: criar o componente do Giscus no projeto Astro. No diretório src/components, crie o arquivo Giscus.astro e cole o código abaixo:

---
// src/components/Giscus.astro
---

<div class="giscus"></div>

<script>
  function loadGiscus() {
    const script = document.createElement('script');
    script.src = 'https://giscus.app/client.js';
    script.setAttribute('data-repo', 'your-username/your-repo'); // Substitua pelo seu repositório
    script.setAttribute('data-repo-id', 'your-repo-id'); // Substitua pelo seu repo-id
    script.setAttribute('data-category', 'Comments');
    script.setAttribute('data-category-id', 'your-category-id'); // Substitua pelo seu category-id
    script.setAttribute('data-mapping', 'pathname');
    script.setAttribute('data-reactions-enabled', '1');
    script.setAttribute('data-emit-metadata', '0');
    script.setAttribute('data-input-position', 'bottom');
    script.setAttribute('data-theme', 'light');
    script.setAttribute('data-lang', 'zh-CN');
    script.setAttribute('crossorigin', 'anonymous');
    script.async = true;

    const container = document.querySelector('.giscus');
    if (container) {
      container.innerHTML = ''; // Limpe o contêiner para evitar carregamentos duplicados
      container.appendChild(script);
    }
  }

  // Inicialize no primeiro carregamento da página
  loadGiscus();

  // [Importante] Monitore o evento de transição do Astro e recarregue os comentários ao trocar de página
  document.addEventListener('astro:page-load', loadGiscus);
</script>

<style>
  .giscus {
    margin-top: 2rem;
  }
</style>

Observe a linha document.addEventListener('astro:page-load', loadGiscus);: ela é a chave para resolver o problema de roteamento com View Transitions. O Astro dispara o evento astro:page-load na troca de página; ao monitorá-lo, recarregamos o componente de comentários a cada navegação e impedimos que ele desapareça.

Use o componente na página do artigo

Abra o arquivo de template dos artigos do seu blog, geralmente src/pages/blog/[...slug].astro ou um caminho parecido, e importe o componente Giscus depois do conteúdo:

---
import Giscus from '@/components/Giscus.astro';
// ...outros imports
---

<article>
  <!-- Conteúdo do artigo -->
  <h1>{title}</h1>
  <div>{content}</div>
</article>

<!-- Área de comentários -->
<Giscus />

Salve o arquivo, inicie o servidor de desenvolvimento com npm run dev, abra um artigo e role até o final: a caixa de comentários já deverá estar visível. Navegue entre artigos diferentes para confirmar que os comentários continuam aparecendo.

Como integrar o Waline: a opção com mais recursos

Se o login pelo GitHub no Giscus for uma barreira e você quiser aceitar comentários anônimos, experimente o Waline. Ele oferece mais recursos, como painel administrativo, estatísticas e notificações por e-mail, mas sua configuração é um pouco mais complexa porque exige um serviço de backend.

Implante o backend com Vercel + LeanCloud

O backend do Waline pode ser implantado em várias plataformas. A combinação mais comum é Vercel + LeanCloud, que é totalmente gratuita.

Etapa 1: crie um aplicativo no LeanCloud

1. Acesse https://console.leancloud.cn/ e crie uma conta; é recomendável escolher a versão internacional, pois a versão chinesa exige o registro ICP do domínio
2. Clique em “Criar aplicativo” e escolha o “Plano de desenvolvimento”, que oferece 1 GB de armazenamento gratuito e é suficiente para um blog pessoal
3. Depois da criação, abra a página “Configurações → Credenciais do aplicativo” e anote estes três valores:
   • App ID, que será usado em LEAN_ID
   • App Key, que será usado em LEAN_KEY
   • Master Key, que será usado em LEAN_MASTER_KEY

Etapa 2: implante o Waline na Vercel

1. Acesse https://vercel.com/new/clone?repository-url=https://github.com/waline/waline/tree/main/example, o link de implantação com um clique fornecido oficialmente pelo Waline
2. Entre na Vercel com sua conta do GitHub
3. Informe um nome para o projeto, como my-waline, e clique em Create
4. A Vercel criará o repositório e fará a implantação automaticamente; o processo leva cerca de 1 a 2 minutos
5. Abra “Settings → Environment Variables” e adicione três variáveis de ambiente:
   • LEAN_ID = seu LeanCloud App ID
   • LEAN_KEY = seu LeanCloud App Key
   • LEAN_MASTER_KEY = seu LeanCloud Master Key
6. Salve, abra “Deployments”, encontre a implantação mais recente, clique nos três pontos à direita e escolha “Redeploy”
7. Depois da implantação, você receberá um domínio como my-waline.vercel.app

Etapa 3: associe um domínio personalizado — importante

Não pule esta etapa. O domínio .vercel.app da Vercel é bloqueado na China; sem um domínio próprio, o serviço de comentários não poderá ser acessado de lá.

1. No seu provedor de domínio, como Alibaba Cloud ou Tencent Cloud, adicione um registro CNAME:
   • Host: waline, ou outro nome de sua preferência
   • Tipo: CNAME
   • Valor: cname.vercel-dns.com
2. Volte à Vercel, abra “Settings → Domains”, informe seu domínio, como waline.yourdomain.com, e clique em Add
3. Aguarde a propagação do DNS, que pode levar de alguns minutos a algumas horas; depois disso, você poderá acessar o Waline pelo seu domínio

Integração com o frontend do Astro

Depois de implantar o backend, integre o código do frontend ao projeto Astro.

Etapa 1: instale o cliente do Waline

npm install @waline/client

Etapa 2: crie o componente Waline

No diretório src/components, crie o arquivo Waline.astro:

---
// src/components/Waline.astro
---

<div id="waline"></div>

<script>
  import { init } from '@waline/client';
  import '@waline/client/style';

  function loadWaline() {
    const walineInstance = init({
      el: '#waline',
      serverURL: 'https://waline.yourdomain.com', // Substitua pelo seu domínio do Waline
      path: window.location.pathname,
      lang: 'zh-CN',
      dark: 'auto', // Adapte automaticamente ao modo escuro
      emoji: [
        '//unpkg.com/@waline/emojis@latest/weibo',
        '//unpkg.com/@waline/emojis@latest/bilibili'
      ],
      meta: ['nick', 'mail'], // Dados do autor: nome e e-mail, sem site
      requiredMeta: ['nick'], // Campo obrigatório: nome
      pageSize: 10,
    });

    // Retorne a instância para poder destruí-la depois
    return walineInstance;
  }

  // Armazene a instância para destruí-la na troca de página
  let walineInstance = null;

  // Primeiro carregamento da página
  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', () => {
      walineInstance = loadWaline();
    });
  } else {
    walineInstance = loadWaline();
  }

  // [Importante] Compatibilidade com o roteamento de View Transitions
  document.addEventListener('astro:page-load', () => {
    // Destrua a instância anterior
    if (walineInstance && walineInstance.destroy) {
      walineInstance.destroy();
    }
    // Recarregue
    walineInstance = loadWaline();
  });
</script>

<style>
  #waline {
    margin-top: 2rem;
  }
</style>

Observe o monitoramento do evento astro:page-load no final. Além de recarregar os comentários, o código primeiro destrói a instância anterior com walineInstance.destroy(), evitando vazamentos de memória.

Etapa 3: use o componente na página do artigo

Assim como no Giscus, importe o componente Waline no template do artigo:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

---
import Waline from '@/components/Waline.astro';
---

<article>
  <!-- Conteúdo do artigo -->
</article>

<Waline />

Cadastre uma conta de administrador

Depois da implantação, acesse https://waline.yourdomain.com/ui/register e crie a primeira conta. Ela se tornará administradora automaticamente e poderá entrar no painel para moderar comentários e consultar estatísticas.

O painel administrativo fica em https://waline.yourdomain.com/ui. Depois de entrar, você poderá excluir spam em lote, exportar dados e usar vários outros recursos.

Como integrar o Twikoo: leve e simples

Twikoo é a opção mais leve entre os três sistemas e oferece diferentes formas de implantação, incluindo Tencent Cloud, Vercel e Cloudflare Workers. A interface é limpa e agradável. Se você não precisa dos recursos administrativos mais complexos do Waline, Twikoo é uma boa escolha.

Implante uma função em nuvem com Cloudflare Workers

Twikoo aceita várias formas de implantação. Aqui, recomendo Cloudflare Workers, que é totalmente gratuito e tem acesso estável na China.

Etapa 1: instale o Twikoo

npm install twikoo

Etapa 2: faça a implantação no Cloudflare Workers

1. Crie uma conta na Cloudflare, caso ainda não tenha uma
2. Abra a página Workers & Pages e clique em “Create Application → Create Worker”
3. Dê um nome ao Worker, como my-twikoo, e clique em Deploy
4. Depois da implantação, clique em “Quick Edit”, apague o código padrão e cole o código da função em nuvem do Twikoo; consulte a documentação oficial em https://twikoo.js.org/
5. Salve e implante. Anote o domínio do Worker, como my-twikoo.your-subdomain.workers.dev

Integração com o frontend do Astro

No diretório src/components, crie o arquivo Twikoo.astro:

---
// src/components/Twikoo.astro
---

<div id="twikoo"></div>

<script>
  function loadTwikoo() {
    // Importe o Twikoo dinamicamente para evitar problemas com SSR
    import('twikoo').then((twikoo) => {
      twikoo.init({
        envId: 'https://my-twikoo.your-subdomain.workers.dev', // Substitua pelo domínio do seu Worker
        el: '#twikoo',
        path: window.location.pathname,
        lang: 'zh-CN',
      });
    });
  }

  // Primeiro carregamento da página
  loadTwikoo();

  // [Importante] Compatibilidade com o roteamento de View Transitions
  document.addEventListener('astro:page-load', () => {
    // Limpe o contêiner para evitar renderização duplicada
    const container = document.getElementById('twikoo');
    if (container) {
      container.innerHTML = '';
      loadTwikoo();
    }
  });
</script>

<style>
  #twikoo {
    margin-top: 2rem;
  }
</style>

Importe o componente Twikoo na página do artigo:

---
import Twikoo from '@/components/Twikoo.astro';
---

<article>
  <!-- Conteúdo do artigo -->
</article>

<Twikoo />

Compatibilidade com Astro: a armadilha do View Transitions

Nos códigos de integração dos três sistemas, talvez você tenha notado esta linha:

document.addEventListener('astro:page-load', loadComment);

Ela é a chave para resolver o problema do roteamento com View Transitions do Astro. Sem essa linha, o componente de comentários carrega apenas na primeira visita à página. Depois que você navega para outro artigo, ele desaparece.

Por que isso acontece?

O View Transitions do Astro funciona de forma parecida com o roteamento de uma aplicação de página única, ou SPA. Ao clicar em um link, o Astro não recarrega a página inteira: ele substitui somente o conteúdo, o que torna a navegação mais rápida e fluida. O problema é que os scripts tradicionais de sistemas de comentários são executados no carregamento da página. Sem uma atualização completa, o script não roda de novo e os comentários “desaparecem”.

Solução

O Astro oferece vários eventos de ciclo de vida. O mais usado é astro:page-load, disparado sempre que o conteúdo termina de carregar, tanto na primeira visita quanto depois de uma troca de rota. Basta monitorar esse evento e reinicializar o componente de comentários sempre que ele ocorrer.

document.addEventListener('astro:page-load', () => {
  // Reinicialize os comentários
  loadComment();
});

Outras soluções, não recomendadas

Existem mais duas alternativas, mas ambas têm limitações.

Opção 1: usar a diretiva transition:persist

O Astro oferece a diretiva transition:persist para manter um elemento intacto durante a troca de página. Parece perfeito, mas pode misturar os comentários: como cada artigo tem uma conversa diferente, preservar o componente pode fazer os comentários do artigo B aparecerem no artigo A.

<!-- Não recomendado: pode misturar os comentários -->
<div id="comments" transition:persist>
  <Giscus />
</div>

Opção 2: desativar as transições de visualização

Se você não conseguir resolver o problema, pode desativar o View Transitions nas páginas dos artigos e voltar ao recarregamento completo tradicional:

---
// src/pages/blog/[...slug].astro
// Não importe o componente <ViewTransitions />
---

Isso, porém, elimina a animação suave da navegação, uma perda que não compensa.

Adaptação à troca de tema

Se o seu blog aceita alternância para o modo escuro, o sistema de comentários também precisa acompanhar o tema. Veja o Giscus como exemplo:

document.addEventListener('theme-change', (e) => {
  const theme = e.detail.theme; // Obtenha o tema atual: light ou dark

  // Envie uma mensagem ao iframe do Giscus para trocar o tema
  const iframe = document.querySelector('iframe.giscus-frame');
  if (iframe) {
    iframe.contentWindow.postMessage(
      { giscus: { setConfig: { theme } } },
      'https://giscus.app'
    );
  }
});

Waline e Twikoo têm APIs semelhantes; consulte a documentação oficial de cada projeto.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Perguntas frequentes

P1: o que fazer se a Vercel estiver bloqueada?

R: Esse é o problema mais comum. O domínio .vercel.app da Vercel sofre envenenamento de DNS na China, o que impede o acesso ao serviço de comentários. A solução é associar seu próprio domínio:

1. No provedor do domínio, adicione um registro CNAME apontando para cname.vercel-dns.com
2. Em Settings → Domains na Vercel, adicione seu domínio
3. Aguarde a propagação do DNS e acesse o serviço de comentários pelo seu domínio

P2: é possível migrar os dados dos comentários?

R: Sim, mas dá trabalho:

• Os dados do Giscus ficam no GitHub Discussions e podem ser exportados como JSON pela GitHub API
• O Waline oferece exportação de dados como CSV ou JSON no painel administrativo
• O Twikoo permite fazer backup e exportar os dados localmente

Para migrar entre sistemas diferentes, é preciso escrever um script de conversão do formato dos dados; não há uma ferramenta pronta.

P3: como evitar spam nos comentários?

R: Os três sistemas têm mecanismos antispam:

• Giscus: usa o sistema antispam do GitHub, então você praticamente não precisa se preocupar
• Waline: inclui o plugin antispam Akismet e permite moderação manual pelo painel administrativo
• Twikoo: oferece filtro de palavras-chave, CAPTCHA, lista de bloqueio de IP e outros recursos

É recomendável ativar a moderação de comentários, para que novos comentários só apareçam após a aprovação de um administrador.

P4: posso usar mais de um sistema de comentários ao mesmo tempo?

R: Tecnicamente, sim, mas não vale a pena. Vários sistemas aumentam o tempo de carregamento e espalham os comentários por plataformas diferentes, dificultando a administração. Se você realmente quiser trocar de sistema, exporte primeiro os dados antigos e depois importe-os no novo.

P5: o que fazer se os comentários demorarem para carregar?

R: Algumas sugestões de otimização:

• Use carregamento sob demanda: inicialize os comentários apenas quando a seção entrar na área visível
• Ative uma CDN: Waline e Twikoo aceitam aceleração por CDN
• Reduza os pacotes de emojis: Waline carrega vários por padrão; mantenha apenas os mais usados

Conclusão

Depois de todos esses detalhes, vamos resumir.

Escolha Giscus se o seu blog é voltado principalmente para programadores ou se você quer uma solução de custo e manutenção zero. É a configuração mais simples, fica pronta em 5 minutos e conta com a infraestrutura nativa do GitHub.

Escolha Waline se você precisa de um painel administrativo robusto ou quer reduzir a barreira para comentar, aceitando mensagens anônimas. É indicado para blogs com muito tráfego e muitos comentários.

Escolha Twikoo se você prefere uma opção leve e simples e não precisa de recursos administrativos complexos. A implantação é flexível e a interface é agradável.

Uso Giscus no meu próprio blog de tecnologia porque todos os leitores são programadores. Entrar com o GitHub não é uma barreira; na verdade, é mais conveniente. E, como é totalmente gratuito, não dá trabalho.

Depois de escolher o sistema, siga o tutorial e conclua a configuração em 10 minutos. Com comentários, o blog ganha interação e fica mais humano. As mensagens, sugestões e críticas dos leitores dão ainda mais motivação para continuar escrevendo.

Se você ainda tiver alguma dúvida, deixe um comentário — claro, desde que já tenha integrado seu sistema. Boa configuração!