Desplegar un sitio Astro en Cloudflare Workers

Un sitio Astro compilado de forma estática es un directorio de HTML, CSS y JavaScript: nada que necesite un servidor en ejecución para renderizarse. Cloudflare Workers puede servir exactamente ese directorio desde centros de datos de todo el mundo, así que el primer byte llega a un lector en Lisboa tan rápido como a uno en São Paulo. Esta guía lleva una build terminada hasta una URL en vivo, configura el despliegue continuo desde GitHub y es honesta sobre dónde te van a apretar los límites de la plataforma.

Lo que ya deberías tener

Esta guía asume un proyecto Astro que compila a salida estática, que es lo predeterminado. Ejecutar astro build produce un directorio dist/, y abrir dist/index.html en local muestra tu sitio. También necesitarás una cuenta de Cloudflare (el plan gratuito basta para seguir la guía) y la CLI wrangler, que se instala como dependencia de desarrollo de npm. Si tu sitio usa renderizado bajo demanda con un adaptador, la historia del despliegue es distinta; esta guía trata específicamente del caso estático, que es lo que quiere la mayoría de los sitios de contenido.

Paso 1 — Describe el despliegue

Cloudflare lee un único archivo, wrangler.toml, para saber qué desplegar. Para un sitio estático, toda la configuración es un nombre, una fecha de compatibilidad y un puntero a tu salida de build.

1
name = "bitkode-site"
2
compatibility_date = "2025-01-01"
3

4
[assets]
5
directory = "./dist"
6
not_found_handling = "404-page"

El bloque [assets] es lo que convierte un Worker en un host estático. directory apunta a la salida de build de Astro. not_found_handling le indica al edge qué hacer cuando una ruta no coincide con ningún archivo: "404-page" sirve tu dist/404.html, que Astro genera automáticamente. Aquí no hay nada de código de servidor: Workers static assets sirve los archivos directamente y se te factura por peticiones, no por cómputo.

Paso 2 — Despliega a mano una vez

Antes de automatizar nada, comprueba que el camino funciona desde tu propia máquina. Compila y despliega:

1
npx astro build
2
npx wrangler deploy

El primer wrangler deploy te pide autenticarte en el navegador, luego sube dist/ e imprime una URL en vivo *.workers.dev. Ábrela. Si tu página de inicio se renderiza y los enlaces internos resuelven, la configuración es correcta y todo lo que sigue trata de hacer esto de forma automática.

Paso 3 — Despliega desde GitHub en cada push

Los despliegues manuales están bien para un primer vistazo y mal para un proyecto real: quieres que main se publique sola. La forma más limpia es un pequeño flujo de GitHub Actions que compila y llama a wrangler deploy por ti.

1
name: Deploy
2
on:
3
  push:
4
    branches: [main]
5

6
jobs:
7
  deploy:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v4
11
      - uses: actions/setup-node@v4
12
        with:
13
          node-version: 20
14
      - run: npm ci
15
      - run: npm run build
16
      - uses: cloudflare/wrangler-action@v3
17
        with:
18
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
19
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

El paso resaltado es el despliegue. wrangler-action lee el mismo wrangler.toml que probaste en local, así que la CI hace exactamente lo que hiciste a mano: sin sorpresas. Crea los dos secretos en la configuración de tu repositorio: un token de API con alcance limitado y el permiso “Edit Workers”, y tu account ID desde el panel de Cloudflare. Nunca los subas al repositorio.

Paso 4 — Vistas previas antes de fusionar

Publicar main de forma automática es solo la mitad de un buen flujo; también quieres ver una rama antes de que se fusione. La integración con Git de Cloudflare (“Workers Builds”) conecta el repositorio directamente y le da a cada rama que no es de producción su propia URL de vista previa, construida en cada push. Como alternativa, manteniendo el enfoque de GitHub Actions, puedes subir una vista previa versionada sin promoverla a producción:

1
npx wrangler versions upload

Esto devuelve una URL de vista previa estable para esa versión exacta, ideal para pegar en un pull request para su revisión. En cualquiera de los dos casos, el objetivo es el mismo: que ningún cambio llegue a la URL de producción sin que un humano lo haya visto antes en algún sitio.

Paso 5 — Apunta un dominio propio

La URL *.workers.dev está bien para pruebas y mal para cualquier cosa en la que quieras que la gente confíe. Si el DNS de tu dominio está en Cloudflare, añade un dominio personalizado al Worker desde la configuración de su panel: Cloudflare aprovisiona el certificado TLS y enruta el dominio a tu Worker automáticamente, normalmente en menos de un minuto. Sin registros DNS que editar a mano, sin certificados que renovar.

Compensaciones que conviene conocer

El hosting estático en el edge es casi ideal para sitios de contenido, pero es un conjunto concreto de decisiones, no una comida gratis. Renuncias a un servidor de origen tradicional, así que cualquier cosa genuinamente dinámica debe moverse a un Worker aparte, a una función serverless o a una llamada del lado del cliente: el host estático no la ejecutará. Heredas los límites de la plataforma que vimos arriba, que premian builds pequeñas y bien comprimidas y castigan las desbordadas. Y acoplas tu entrega al edge de un solo proveedor; la salida de build es portable, pero el wrangler.toml, el flujo de vistas previas y el cableado del dominio son específicos de Cloudflare. Para un sitio de contenido en Astro, esas son compensaciones fáciles de aceptar: baja latencia global y facturación por petición a cambio de quedarte dentro del modelo estático.

Ideas clave

Una build estática de Astro es solo un directorio; Workers static assets lo sirve desde el edge, facturado por petición, no por segundo de cómputo.
Toda la configuración de despliegue es un bloque [assets] en wrangler.toml que apunta a dist/: sin código de servidor.
Automatiza con un pequeño flujo de GitHub Actions que ejecute wrangler deploy; guarda el token de API y el account ID en los secretos del repositorio.
Usa URLs de vista previa por rama (Workers Builds o wrangler versions upload) para que nada llegue a producción sin revisar.
Vigila los límites de conteo y tamaño de archivos: premian builds pequeñas y comprimidas, y harán fallar un despliegue que los desborde.

Despliega main, dale a cada rama una vista previa y ponle encima un dominio real. A partir de ahí el sitio es solo archivos en el edge, que es exactamente lo que un sitio de contenido quiere ser.