Integra un sistema de comentarios en tu blog Astro: guía completa con Giscus, Waline y Twikoo

Añadir comentarios a un blog Astro me costó más de lo que pensaba.

Al principio parecía sencillo: instalar un sistema de comentarios y listo. Pero al ponerme manos a la obra vi que hay demasiadas opciones: Giscus, Waline, Twikoo, Disqus… cada una promete ser la mejor y cada una se configura de forma distinta. Peor aún: sigues un tutorial, todo parece funcionar, abres el blog y los comentarios se ven bien. Dos segundos de alegría. Cambias a otro artículo y desaparecen.

Después supe que la culpa era el enrutamiento con transiciones de vista (View Transitions) de Astro. Al cambiar de página, el componente de comentarios no se recarga y acabas con comentarios de Schrödinger: no sabes si los verás hasta que haces clic.

Si te pasa lo mismo o no sabes qué sistema elegir, este artículo te ayudará. Comparo tres opciones populares (Giscus, Waline y Twikoo), incluyo código completo de integración en Astro y resuelvo la compatibilidad con View Transitions. Al terminar puedes configurarlo en unos 10 minutos.

Comparativa de sistemas de comentarios: ¿cuál elegir?

Los tres los he probado; cada uno tiene ventajas. Primero, una tabla resumida:

Mis recomendaciones

Si la tabla no basta, aquí va más concreto:

Si tu blog va dirigido a programadores —tutoriales técnicos, documentación open source— elige Giscus. Tus lectores ya tienen cuenta de GitHub; iniciar sesión con GitHub es incluso más cómodo. Además es solo frontend, sin backend, y se configura en unos 5 minutos.

Si tu blog va al público general —vida cotidiana, fotografía, viajes— elige Waline o Twikoo. Ambos permiten comentarios anónimos y bajan la barrera de participación: sin registro ni login, solo nick y email. Waline tiene un panel de administración más potente para blogs con muchos comentarios; Twikoo es más ligero y algo más fácil de desplegar.

Si buscas coste cero, como yo, elige Giscus sin dudar. Solo usa servicios gratuitos de GitHub: sin base de datos extra, sin nube de pago, ni siquiera servidor. Waline también tiene plan gratuito (LeanCloud dev 1 GB), pero con mucho tráfico puede hacer falta un plan de pago.

Si necesitas un panel de administración potente —moderación, estadísticas, filtro de spam— elige Waline. Tiene panel dedicado para gestionar comentarios en lote y ver estadísticas, similar a los plugins de comentarios de WordPress.

En resumen: blogs técnicos con Giscus, estilo de vida con Waline, minimalismo con Twikoo.

Tutorial de integración de Giscus: la opción más simple

Giscus es el que más recomiendo, sobre todo para blogs técnicos. Es el más fácil de los tres: sin backend, sin base de datos, solo servicios gratuitos de GitHub.

Preparación

Antes de integrar Giscus:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

1. Crear un repositorio público en GitHub

Puedes usar el repo del código del blog o crear uno solo para comentarios (por ejemplo blog-comments). Debe ser público; en repos privados los comentarios no se muestran.

2. Activar Discussions

En Settings del repositorio, baja hasta Features y activa Discussions. Viene desactivado por defecto.

3. Instalar la app giscus

Visita https://github.com/apps/giscus, pulsa Install y elige el repositorio. Autorizas al bot giscus para crear y gestionar Discussions.

4. Configurar categorías de Discussion

Abre Discussions del repo y Categories arriba a la derecha. Conviene crear una categoría tipo Announcements (por ejemplo “Comments”): solo tú y el bot pueden abrir temas; el resto solo responde, lo que reduce spam.

Obtener parámetros de configuración

Con la preparación hecha, visita https://giscus.app/zh-CN y rellena el formulario:

1. Nombre del repositorio: tu-usuario/nombre-repo, por ejemplo zhangsan/blog-comments
2. Mapeo página–Discussion: recomiendo pathname; cada URL crea su Discussion automáticamente
3. Categoría de Discussion: la categoría Announcements que creaste
4. Tema: light, dark o preferred_color_scheme para adaptarse al sistema

Al final verás código con data-repo, data-repo-id, data-category-id, etc. Guárdalos; los usarás en Astro.

Código de integración en Astro

Crea el componente Giscus en src/components/Giscus.astro:

---
// 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'); // 改成你的仓库
    script.setAttribute('data-repo-id', 'your-repo-id'); // 改成你的repo-id
    script.setAttribute('data-category', 'Comments');
    script.setAttribute('data-category-id', 'your-category-id'); // 改成你的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 = ''; // 清空容器，避免重复加载
      container.appendChild(script);
    }
  }

  // 页面首次加载时初始化
  loadGiscus();

  // 【关键】监听Astro的视图过渡事件，页面切换时重新加载评论
  document.addEventListener('astro:page-load', loadGiscus);
</script>

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

Fíjate en document.addEventListener('astro:page-load', loadGiscus);: es la clave para View Transitions. Astro dispara astro:page-load en cada carga de contenido (inicial y al navegar); al escucharlo recargas los comentarios y no desaparecen.

Usar en la página del artículo

En la plantilla del artículo (por ejemplo src/pages/blog/[...slug].astro), importa Giscus después del contenido:

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

<article>
  <!-- 博客文章内容 -->
  <h1>{title}</h1>
  <div>{content}</div>
</article>

<!-- 评论区 -->
<Giscus />

Guarda, ejecuta npm run dev, abre un artículo y baja hasta el formulario de comentarios. Navega entre artículos: los comentarios deberían seguir visibles.

Tutorial de integración de Waline: el más completo

Si el login de GitHub de Giscus es demasiado restrictivo y quieres comentarios anónimos, prueba Waline. Tiene más funciones que Giscus —panel de administración, estadísticas, email— pero la configuración es algo más compleja porque requiere backend.

Desplegar backend (Vercel + LeanCloud)

El backend de Waline puede ir en varias plataformas; lo más habitual es Vercel + LeanCloud, gratis.

Paso 1: Crear aplicación en LeanCloud

1. Visita https://console.leancloud.cn/ y regístrate (la edición internacional evita requisitos de registro de dominio en China)
2. Crea una aplicación en plan “开发版” (dev, 1 GB gratis, suficiente para un blog personal)
3. En “设置 → 应用凭证” anota:
   • App ID (para LEAN_ID)
   • App Key (para LEAN_KEY)
   • Master Key (para LEAN_MASTER_KEY)

Paso 2: Desplegar Waline en Vercel

1. Visita https://vercel.com/new/clone?repository-url=https://github.com/waline/waline/tree/main/example (enlace oficial de despliegue en un clic)
2. Inicia sesión en Vercel con GitHub
3. Pon un nombre al proyecto (por ejemplo my-waline) y Create
4. Vercel crea el repo y despliega; en 1-2 minutos debería estar listo
5. En “Settings → Environment Variables” añade:
   • LEAN_ID = tu LeanCloud App ID
   • LEAN_KEY = tu LeanCloud App Key
   • LEAN_MASTER_KEY = tu LeanCloud Master Key
6. Guarda, ve a “Deployments”, abre el menú del último despliegue y Redeploy
7. Obtendrás un dominio como my-waline.vercel.app

Paso 3: Vincular dominio propio (¡importante!)

No lo omitas. El dominio .vercel.app puede estar bloqueado en algunas redes; sin dominio propio el servicio de comentarios podría no ser accesible.

1. En tu proveedor DNS (Alibaba Cloud, Tencent Cloud, etc.) añade un CNAME:
   • Host: waline (u otro nombre)
   • Tipo: CNAME
   • Valor: cname.vercel-dns.com
2. En Vercel, “Settings → Domains”, añade tu dominio (por ejemplo waline.tudominio.com)
3. Espera la propagación DNS (minutos u horas); luego accede con tu dominio

Integración frontend en Astro

Con el backend listo, integra el frontend.

Paso 1: Instalar cliente Waline

npm install @waline/client

Paso 2: Crear componente Waline

Crea src/components/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', // 改成你的Waline域名
      path: window.location.pathname,
      lang: 'zh-CN',
      dark: 'auto', // 自动适配暗色模式
      emoji: [
        '//unpkg.com/@waline/emojis@latest/weibo',
        '//unpkg.com/@waline/emojis@latest/bilibili'
      ],
      meta: ['nick', 'mail'], // 评论者信息：昵称、邮箱（隐藏网址）
      requiredMeta: ['nick'], // 必填项：昵称
      pageSize: 10,
    });

    // 返回实例，方便后续销毁
    return walineInstance;
  }

  // 存储实例，方便页面切换时销毁
  let walineInstance = null;

  // 页面首次加载
  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', () => {
      walineInstance = loadWaline();
    });
  } else {
    walineInstance = loadWaline();
  }

  // 【关键】视图过渡路由兼容
  document.addEventListener('astro:page-load', () => {
    // 销毁旧实例
    if (walineInstance && walineInstance.destroy) {
      walineInstance.destroy();
    }
    // 重新加载
    walineInstance = loadWaline();
  });
</script>

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

En astro:page-load no solo recargamos: primero destruimos la instancia anterior (walineInstance.destroy()) para evitar fugas de memoria.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Paso 3: Usar en la página del artículo

Igual que con Giscus:

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

<article>
  <!-- 文章内容 -->
</article>

<Waline />

Registrar cuenta de administrador

Tras el despliegue, visita https://waline.yourdomain.com/ui/register y registra la primera cuenta; será administrador automáticamente. El panel está en https://waline.yourdomain.com/ui: moderación, estadísticas, exportación, etc.

Tutorial de integración de Twikoo: ligero y limpio

Twikoo es el más ligero de los tres. Se despliega de varias formas (Tencent Cloud, Vercel, Cloudflare Workers) y la interfaz es clara. Si no necesitas el panel complejo de Waline, Twikoo es buena opción.

Desplegar función en la nube (Cloudflare Workers)

Recomiendo Cloudflare Workers: gratis y con buen acceso.

Paso 1: Instalar Twikoo

npm install twikoo

Paso 2: Desplegar en Cloudflare Workers

1. Crea cuenta en Cloudflare si no tienes
2. Workers & Pages → “Create Application → Create Worker”
3. Nombre del Worker (por ejemplo my-twikoo) → Deploy
4. “Quick Edit”, borra el código por defecto y pega el de la función Twikoo (documentación: https://twikoo.js.org/)
5. Guarda y despliega; anota el dominio (por ejemplo my-twikoo.tu-subdominio.workers.dev)

Integración frontend en Astro

Crea src/components/Twikoo.astro:

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

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

<script>
  function loadTwikoo() {
    // 动态导入Twikoo，避免SSR问题
    import('twikoo').then((twikoo) => {
      twikoo.init({
        envId: 'https://my-twikoo.your-subdomain.workers.dev', // 改成你的Worker域名
        el: '#twikoo',
        path: window.location.pathname,
        lang: 'zh-CN',
      });
    });
  }

  // 页面首次加载
  loadTwikoo();

  // 【关键】视图过渡路由兼容
  document.addEventListener('astro:page-load', () => {
    // 清空容器，避免重复渲染
    const container = document.getElementById('twikoo');
    if (container) {
      container.innerHTML = '';
      loadTwikoo();
    }
  });
</script>

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

En la página del artículo:

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

<article>
  <!-- 文章内容 -->
</article>

<Twikoo />

Compatibilidad con Astro: el problema de View Transitions

En los tres tutoriales verás esta línea:

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

Es la clave para View Transitions. Sin ella, los comentarios solo cargan en la primera visita; al navegar a otro artículo desaparecen.

¿Por qué ocurre?

View Transitions de Astro se parece al cambio de ruta en una SPA: no recarga toda la página, solo sustituye el contenido. Más rápido y fluido, pero los scripts de comentarios suelen ejecutarse al cargar la página completa. Sin recarga, no se vuelven a ejecutar y los comentarios “desaparecen”.

Solución

Astro expone eventos del ciclo de vida; el más útil es astro:page-load, que se dispara tras cada carga de contenido (inicial y por navegación). Escúchalo y reinicializa el componente de comentarios.

document.addEventListener('astro:page-load', () => {
  // 重新初始化评论
  loadComment();
});

Otras soluciones (no recomendadas)

Hay dos alternativas con inconvenientes:

Opción 1: directiva transition:persist

Mantiene un elemento al cambiar de página. Suena bien, pero mezcla comentarios: el artículo A podría mostrar los del artículo B.

<!-- 不推荐！会导致评论错乱 -->
<div id="comments" transition:persist>
  <Giscus />
</div>

Opción 2: desactivar View Transitions

Puedes quitar View Transitions en las páginas de artículo y volver a recargas completas:

---
// src/pages/blog/[...slug].astro
// 不导入<ViewTransitions />组件
---

Pierdes las transiciones fluidas; no compensa.

Adaptación al cambio de tema

Si el blog tiene modo oscuro, los comentarios deben seguir el tema. Ejemplo con Giscus:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

document.addEventListener('theme-change', (e) => {
  const theme = e.detail.theme; // 获取当前主题（light/dark）

  // 向Giscus iframe发送消息，切换主题
  const iframe = document.querySelector('iframe.giscus-frame');
  if (iframe) {
    iframe.contentWindow.postMessage(
      { giscus: { setConfig: { theme } } },
      'https://giscus.app'
    );
  }
});

Waline y Twikoo tienen APIs similares; consulta su documentación.

Preguntas frecuentes

P1: ¿Qué hacer si Vercel está bloqueado?

Es habitual: el dominio .vercel.app puede no resolverse en algunas redes. Solución: dominio propio.

1. CNAME en tu DNS apuntando a cname.vercel-dns.com
2. Añade el dominio en Vercel → Settings → Domains
3. Tras propagar DNS, usa tu dominio para el servicio de comentarios

P2: ¿Se pueden migrar los comentarios?

Sí, pero requiere trabajo:

• Giscus: datos en GitHub Discussions, exportables vía API en JSON
• Waline: exportación en el panel a CSV o JSON
• Twikoo: copia de seguridad a local

Migrar entre sistemas implica scripts propios; no hay herramienta universal.

P3: ¿Cómo evitar spam?

Los tres incluyen protección:

• Giscus: sistema anti-spam de GitHub
• Waline: plugin Akismet y moderación manual
• Twikoo: filtro por palabras clave, captcha, lista negra de IP

Activa moderación para aprobar comentarios nuevos antes de publicarlos.

P4: ¿Puedo usar varios sistemas a la vez?

Técnicamente sí, pero no tiene sentido: más carga y comentarios repartidos. Si cambias de sistema, exporta antes e importa al nuevo.

P5: ¿Los comentarios cargan lento?

Algunas optimizaciones:

• Carga diferida: inicializar al entrar en el viewport
• CDN: Waline y Twikoo admiten CDN
• Menos paquetes de emoji en Waline

Resumen

Giscus si tu blog es técnico o quieres coste y mantenimiento cero. Configuración más simple, unos 5 minutos, integración nativa con GitHub.

Waline si necesitas panel de administración potente o comentarios anónimos. Ideal para mucho tráfico y volumen de comentarios.

Twikoo si prefieres algo ligero sin funciones de gestión complejas. Despliegue flexible e interfaz limpia.

En mi blog técnico uso Giscus: mis lectores son desarrolladores, GitHub no es barrera sino ventaja, y es gratis.

Elige, sigue el tutorial y en unos 10 minutos lo tienes. Los comentarios aportan interacción y motivación para seguir escribiendo.

Si tienes más dudas, déjalas en los comentarios (sí, cuando ya los hayas integrado). ¡Buena configuración!