Guía completa para desplegar blogs estáticos en Cloudflare Pages: 5 frameworks sin errores

Terminaste el primer artículo del blog y pulsaste Desplegar. Tres minutos después Cloudflare Pages mostró éxito; copiaste el enlace al navegador y la página estaba en blanco. F12 en la consola: 404 por todas partes.

La primera vez que desplegué un blog Astro fue así: respuestas contradictorias en Google, tres o cuatro horas de pruebas, y al final el directorio de salida estaba en public cuando Astro usa dist por defecto.

El 90% de los fallos de despliegue se reducen a dos ajustes: comando de build y directorio de salida. Este artículo te da la configuración exacta en Cloudflare Pages para Astro, Hugo, Hexo, Gatsby y Eleventy, y cómo resolver rápido páginas en blanco y builds fallidos. Sigue los pasos y en 10 minutos pasas de Git a producción.

¿Por qué Cloudflare Pages? (pero ten en cuenta los cambios de 2025)

Primero, por qué recomiendo Cloudflare Pages para blogs estáticos.

Gratis y de verdad rápido. Cloudflare tiene más de 300 centros de datos en el mundo. Tu blog se distribuye automáticamente y los lectores acceden rápido desde cualquier sitio. He usado GitHub Pages y Vercel; Cloudflare Pages es más estable en velocidad, sobre todo para visitantes desde China. Es totalmente gratis, sin límite de tráfico ni de builds.

El despliegue automático desde Git ahorra trabajo. Conectas GitHub o GitLab y, con cada git push, Cloudflare compila y despliega. También genera enlaces de vista previa por Pull Request, útil para revisar antes de fusionar. Muy práctico en equipo.

SSL gratuito y dominio personalizado incluidos. Sin pelearte con certificados; enlazar tu dominio es sencillo y el DNS suele propagarse en minutos.

Pero hay que decirlo: en abril de 2025 Cloudflare ajustó su estrategia, empuja Cloudflare Workers y Pages entra en modo mantenimiento, sin grandes actualizaciones.

Para blogs estáticos, el cambio casi no afecta. Pages sigue estable y con funciones de sobra. Si solo quieres un blog o documentación, sin SSR complejo ni edge computing, Pages sigue siendo la mejor opción. Workers encaja mejor con funciones dinámicas, rutas API o edge computing avanzado.

En resumen: si despliegas un blog puramente estático ahora, usa Pages con tranquilidad. Si más adelante necesitas servidor, migrar a Workers no es tarde.

Configuración estándar de 5 frameworks (sección clave)

Aquí va lo importante: la configuración exacta de los cinco generadores estáticos más usados. Cópiala tal cual.

Tabla rápida de configuración

Guarda esta tabla: he verificado cada configuración. Abajo detallo los puntos delicados por framework.

Configuración de Astro

Astro es mi framework favorito para blogs estáticos: buen rendimiento y agradable de escribir.

Configuración estándar:

• Comando de build: npm run build o directamente astro build
• Directorio de salida: dist

Si es un sitio puramente estático (SSG), la configuración por defecto basta. Pero hay un detalle: para renderizado en servidor (SSR) instala el adaptador @astrojs/cloudflare y añade en astro.config.mjs:

import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'server',
  adapter: cloudflare()
};

Si quieres cambiar el directorio de salida (por ejemplo a build), puedes hacerlo en la configuración:

export default {
  outDir: 'build'
};

Yo no lo cambiaría: usa dist por defecto y evitas confusiones en equipo.

Configuración de Hugo (la que más falla)

Hugo tiene más trampas. La primera vez que desplegué un blog Hugo me costó toda una noche entenderlo.

Configuración estándar:

• Comando de build: hugo o hugo -b $CF_PAGES_URL
• Directorio de salida: public
• Variable de entorno (obligatoria): HUGO_VERSION = 0.143.1 (o la versión que necesites)

Lo clave: Cloudflare Pages usa Hugo 0.54 por defecto, ¡versión de 2019! Casi todos los temas actuales piden 0.80 o más, incluso 0.120+. Sin HUGO_VERSION manual, el despliegue fallará.

¿Cómo definirla? En la sección de flujo práctico lo explico con detalle; por ahora recuerda: en el proyecto de Cloudflare Pages, Settings > Environment variables, añade:

• Nombre: HUGO_VERSION
• Valor: 0.143.1 (versión exacta; no escribas 0.143)

Otro detalle: baseURL de Hugo. Si usas el dominio .pages.dev de Cloudflare (no un dominio propio), el comando de build debería ser:

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

Obtener 15% dto. →Anuncio

hugo -b $CF_PAGES_URL

$CF_PAGES_URL es una variable que Cloudflare define automáticamente según el entorno. Así enlaces internos, RSS y sitemap funcionan bien.

Configuración de Hexo

Hexo es un generador veterano; la configuración es relativamente simple.

Configuración estándar:

• Comando de build: hexo generate (también vale hexo g)
• Directorio de salida: public

Hexo rara vez da problemas, pero algunos temas o plugins exigen una versión concreta de Node.js. Si el build falla, prueba con la variable NODE_VERSION:

• Nombre: NODE_VERSION
• Valor: 14.3 o 18.17.0 (según tu proyecto)

En local ejecuta node -v y usa la misma versión en Cloudflare Pages.

Configuración de Gatsby

Gatsby es el más tranquilo; casi nunca falla.

Configuración estándar:

• Comando de build: gatsby build
• Directorio de salida: public

Nada más. He desplegado varios blogs Gatsby de amigos sin un solo problema.

Configuración de Eleventy

Eleventy (11ty) es un generador ligero; también es sencillo.

Configuración estándar:

• Comando de build: npx @11ty/eleventy
• Directorio de salida: _site (con guion bajo al inicio)

Cuidado: es _site, no site. Si omites el guion bajo, no encontrará los archivos.

Para personalizar el directorio de salida, crea .eleventy.js en la raíz:

module.exports = function(eleventyConfig) {
  return {
    dir: {
      output: "public"
    }
  };
};

Configuración de Next.js (cambios de 2025)

Si usas Next.js para el blog, en 2025 hay un cambio importante.

Configuración estándar (esquema 2025):

• Comando de build: npx opennextjs-cloudflare
• Directorio de salida: .worker-next

Importante: muchos tutoriales antiguos usan @cloudflare/next-on-pages, ya obsoleto. Cloudflare recomienda @opennextjs/cloudflare.

Si un tutorial sigue hablando de next-on-pages, ignóralo. Pasos del esquema nuevo:

1. Instala: npm install @opennextjs/cloudflare
2. Comando de build: npx opennextjs-cloudflare
3. Directorio de salida: .worker-next

Si solo quieres un blog estático, no recomiendo Next.js. Encaja mejor en apps dinámicas; para contenido estático puro, Astro o Hugo son más ligeros y rápidos.

Práctica: del repositorio Git a producción (paso a paso)

Ya conoces la configuración; ahora el despliegue desde cero. Unos 10 minutos en total.

Preparación

Antes de empezar, confirma tres cosas:

1. El código está en GitHub o GitLab — abre el repositorio y verifica que el código más reciente está subido
2. El proyecto tiene package.json (si es Node.js) — las dependencias deben estar declaradas; no instales en local sin añadirlas al archivo
3. Revisa .gitignore — node_modules, dist, public y similares deben ignorarse; no subas artefactos de build

Un amigo subió node_modules a Git y el despliegue se llenó de conflictos. Revisa .gitignore y te ahorras dolores de cabeza.

Pasos detallados de despliegue

Paso 1: inicia sesión en Cloudflare y entra en Pages

Abre dash.cloudflare.com e inicia sesión (registro gratis si no tienes cuenta).

En el menú lateral busca Workers & Pages, entra y pulsa Create application arriba a la derecha.

Paso 2: elige Conectar a Git

Verás dos opciones:

• Connect to Git — despliegue automático desde GitHub/GitLab (esta)
• Direct Upload — subida manual (no recomendado)

Elige Connect to Git y luego GitHub o GitLab.

Paso 3: autoriza el acceso

La primera vez debes autorizar a Cloudflare. Pulsa Sign in; irás a la página de autorización de GitHub/GitLab.

Permisos: si no quieres dar acceso a todos los repos, elige Only select repositories.

Tras autorizar volverás a Cloudflare.

Paso 4: selecciona el repositorio

Busca tu proyecto de blog en la lista y haz clic.

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

Empezar →Anuncio

Si no aparece, actualiza arriba a la derecha o vuelve a autorizar.

Paso 5: configuración de build (¡clave!)

La parte más importante; no la rellenes mal.

• Project name: formará parte de tu dominio .pages.dev. Si pones my-blog, será my-blog.pages.dev.
• Production branch: normalmente main o master.
• Framework preset: elige tu framework (Astro, Hugo, etc.) o None.

Build settings

Rellena según la tabla anterior:

• Build command:
  • Astro: npm run build
  • Hugo: hugo o hugo -b $CF_PAGES_URL
  • Hexo: hexo generate
  • Gatsby: gatsby build
  • Eleventy: npx @11ty/eleventy
  • Next.js: npx opennextjs-cloudflare
• Build output directory:
  • Astro: dist
  • Hugo: public
  • Hexo: public
  • Gatsby: public
  • Eleventy: _site
  • Next.js: .worker-next

Si eliges Framework preset, Cloudflare rellena valores por defecto, pero conviene revisarlos.

Paso 6: variables de entorno (si hacen falta)

Baja hasta Environment variables (advanced) y pulsa Add variable.

• Hugo (obligatorio):
  • Variable name: HUGO_VERSION
  • Value: 0.143.1 (o la versión exacta que necesites)
• Hexo (si hace falta):
  • Variable name: NODE_VERSION
  • Value: 14.3 o 18.17.0 (según tu entorno local)

Paso 7: guardar y desplegar

Revisa todo y pulsa Save and Deploy.

Cloudflare compilará el proyecto; verás el log en tiempo real. Suele tardar 1-3 minutos.

Paso 8: revisar el resultado

Si todo va bien verás Success! Your site is live! y un enlace tunombre.pages.dev.

Ábrelo; si la configuración es correcta, verás tu blog.

Variables de entorno en detalle

Puedes definirlas durante el despliegue inicial o después:

1. Entra en tu proyecto de Cloudflare Pages
2. Abre Settings
3. En el menú lateral elige Environment variables
4. Pulsa Add variable
5. Rellena nombre y valor y guarda

Variables habituales:

• HUGO_VERSION: versión de Hugo (p. ej. 0.143.1)
• NODE_VERSION: versión de Node.js (p. ej. 18.17.0)
• CF_PAGES_URL: la proporciona Cloudflare; no la configures a mano; sirve para baseURL

Importante: tras cambiar variables debes redesplegar. Ve a Deployments, localiza el último despliegue, pulsa los tres puntos y elige Retry deployment.

Despliegues de vista previa (Preview Deployments)

Cada Pull Request genera automáticamente un enlace de vista previa.

Si abres un PR en GitHub con un artículo nuevo, Cloudflare compila ese código y te da una URL independiente para revisar antes de fusionar a la rama principal.

Muy útil cuando varias personas escriben en el mismo blog.

¿Problemas? Errores frecuentes y cómo depurarlos

Tres errores cubren el 95% de los casos.

Problema 1: fallo de build (Building Failed)

Síntomas: el despliegue se queda en Building y luego muestra Build failed, con icono rojo.

Es el que más he visto. No redespliegues a ciegas; mira primero el log.

Pasos:

1. Revisa el log de build
   • Pulsa View build log o Deployment details
   • Baja al final y busca el error en rojo
   • Fíjate en las últimas líneas
2. Comprueba el comando de build
   • Ve a Settings > Build & deployments
   • Verifica Build command según la tabla
   • Error típico: npm build en lugar de npm run build
3. Comprueba las dependencias
   • Si aparece Cannot find module o Command not found
   • Revisa package.json; puede que instalaste en local sin guardar la dependencia (npm install --save)
4. Confirma la versión del framework
   • Hugo: el 99% de fallos es por no definir HUGO_VERSION
     • El log puede decir Theme requires Hugo Extended version
     • Añade HUGO_VERSION = 0.143.1 en Environment variables
   • Hexo: puede ser versión de Node.js
     • Prueba NODE_VERSION = 18.17.0 (o tu versión local)

Caso real: un amigo desplegaba Hugo y el log decía Hugo version 0.54.0 does not support this theme. Añadimos HUGO_VERSION = 0.120.0 y el siguiente despliegue pasó al instante.

Problema 2: página en blanco (el más común)

Síntomas: despliegue exitoso pero sitio en blanco; F12 puede mostrar muchos 404.

El 90% de las veces es directorio de salida incorrecto.

Pasos:

1. Herramientas de desarrollo (F12)
   • Console: errores
   • Network: recarga y mira los 404
   • Sources: estructura de archivos
2. Directorio de salida (~90% de los casos)
   • Ve a Settings > Build & deployments
   • Comprueba Build output directory
   • Errores típicos:
     • Astro con public en lugar de dist
     • Hugo con dist en lugar de public
     • Eleventy con site en lugar de _site
3. baseURL o publicPath
   • En subpaths (p. ej. example.com/blog) puede hacer falta baseURL
   • Hugo: hugo -b $CF_PAGES_URL
   • Astro: base: '/blog' en astro.config.mjs
   • Vue/React: a veces publicPath: './'
4. Modo de enrutamiento (SPA)
   • Vue Router o React Router en modo history pueden dar 404 al refrescar
   • Soluciones:
     • Modo hash (URL con #)
     • O archivo _redirects en la raíz:

       /* /index.html 200
       

Caso real: desplegué mi blog Astro y la página estaba en blanco. El directorio de salida era public; al cambiarlo a dist funcionó. A veces el error es así de simple.

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

Ver precios →Anuncio

Problema 3: estilos o recursos que no cargan

Síntomas: el HTML aparece pero sin CSS, imágenes rotas, aspecto roto.

Pasos:

1. Network en las herramientas de desarrollo
   • ¿CSS, JS o imágenes en 404?
   • ¿Las rutas de solicitud son correctas?
2. Rutas de recursos
   • Problema típico: rutas absolutas vs relativas
   • /assets/style.css en un subpath no se resuelve
   • Solución: usa las utilidades del framework
     • Astro: import de recursos
     • Hugo: .RelPermalink o absURL
     • Hexo: url_for()
3. CDN externo
   • Si usas jsDelivr, cdnjs, etc.
   • Comprueba que los enlaces funcionan desde tu región

Caso real: un blog Hexo se veía sin estilos. El CSS apuntaba a /css/style.css pero el sitio estaba en /blog/css/style.css. El blog vivía en un subpath y en _config.yml faltaba root: /blog/. Tras corregirlo y regenerar, todo cuadró.

Lista rápida de comprobación

1. ✓ Revisa el log de build
2. ✓ Confirma el comando de build (tabla)
3. ✓ Confirma el directorio de salida (tabla)
4. ✓ Variables de entorno (HUGO_VERSION en Hugo)
5. ✓ F12: consola y red
6. ✓ .gitignore: no subir artefactos de build
7. ✓ Prueba en local: npm run build, hugo, etc.

Si tras todo sigue fallando, pregunta en el foro de Cloudflare o consulta Troubleshooting en la documentación oficial.

Trucos avanzados: un blog más profesional

El blog en línea es solo el comienzo. Cuatro mejoras sencillas que marcan diferencia.

Dominio personalizado

.pages.dev funciona, pero un dominio propio es más profesional. Cloudflare incluye SSL gratis.

Pasos:

1. Compra un dominio (GoDaddy, Alibaba Cloud, Tencent Cloud, etc.)
2. En tu proyecto de Pages abre Custom domains
3. Pulsa Set up a custom domain e introduce el dominio (p. ej. blog.example.com)
4. Cloudflare te dará registros DNS; añádelos en tu registrador
5. Espera la propagación (minutos u horas)
6. Cloudflare configurará HTTPS automáticamente

Truco: si el dominio también está en Cloudflare, el DNS es más rápido y a veces se configura solo.

Optimizar el build

Con muchos artículos, el build puede alargarse.

1. Caché
   • Pages cachea node_modules por defecto
   • Si es lento, comprueba si reinstala dependencias cada vez
2. Menos dependencias
   • Limpia package.json
   • Librerías por CDN (jQuery, etc.) no hace falta empaquetarlas
3. Paralelismo
   • Hugo: --gc limpia caché y a veces acelera
   • Astro: experimental.contentCollectionCache
4. Estrategia de ramas
   • Trabaja en dev; fusiona a main solo para publicar
   • Así no disparas build de producción en cada commit

Monitorización y analítica

Cloudflare ofrece analítica gratuita.

Datos de visita:

1. Entra en tu proyecto de Pages
2. Abre Analytics
3. Verás:
   • Requests totales
   • Ancho de banda
   • País de origen
   • Tendencias de tráfico

Web Vitals:

• Métricas de carga, interactividad, etc.
• Útil para optimizar (comprimir imágenes, lazy loading, etc.)

Automatización con GitHub Actions

Para ir más allá:

Ejemplo 1: publicación programada

• Artículos con fecha futura; Actions los publica a su hora

Ejemplo 2: sitemap automático

• Tras cada despliegue, enviar sitemap a buscadores

Ejemplo 3: compresión de imágenes

• Antes del push, optimizar assets

No son obligatorios, pero facilitan la operación. En la comunidad hay plantillas listas.

Conclusión

Desplegar un blog estático no es tan complicado. Lo esencial son comando de build y directorio de salida. Con la tabla correcta evitas el 90% de problemas.

Resumen final — guarda esta tabla:

Si algo falla, suele ser configuración. Mira el log, repasa la lista de comprobación y casi siempre lo resuelves.

Pruébalo ahora. Abre Cloudflare Pages, conecta tu repositorio, rellena la configuración correcta y en 10 minutos tu blog puede estar en línea.

Si este artículo te ayudó, compártelo con quien esté peleándose con el despliegue. Si te encuentras un caso que no cubrimos, deja un comentario; puede ayudar a otros.

¡Buen despliegue y buena escritura!