--- title: "Cómo migrar Astro a Bun en Cloudflare Pages (guía 2026)" description: "Migra tu proyecto de Astro de Node.js a Bun en Cloudflare Pages. Guía paso a paso con comandos de compilación, configuración de BUN_VERSION, verificación y resolución de problemas." date: 2024-03-19 categories: ["web-development"] tags: ["bun","astro","cloudflare-pages"] --- import YouTubeEmbed from "@components/widgets/YouTubeEmbed.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; import Accordion from "@components/widgets/Accordion.astro"; Cambiar Node.js y npm por Bun en Cloudflare Pages puede reducir los tiempos de instalación de dependencias entre 10 y 30 veces y recortar entre un 15 y un 30 % las compilaciones con mucha E/S. Bun es un runtime de compilación compatible en Cloudflare Pages, no un experimento. Si tienes un sitio estático de Astro con Node.js y npm, esta guía cubre la migración completa. Tanto si [creaste un blog gratis con Astro y Cloudflare](/es/crear-blog-astro-gratis/) como si [migraste de WordPress a Astro](/es/migracion-wordpress-a-astro/), el cambio a Bun es el siguiente paso para conseguir despliegues más rápidos. El vídeo de arriba muestra el flujo de migración original de 2024. La guía escrita de abajo está totalmente actualizada para 2025 con las versiones actuales de Bun, los cambios en el sistema de compilación de Cloudflare y nuevos consejos de resolución de problemas. ## Requisitos previos y compatibilidad ### Compatibilidad de versiones de Astro Esta migración funciona igual de Astro v3 a v7 en sitios estáticos (SSG). Astro 7 añadió un compilador en Rust y Rolldown (Vite 8), lo que se traduce en compilaciones más rápidas. Puedes leer más sobre el [rendimiento de compilación de Astro 7](/es/astro-7-compilaciones-mas-rapidas/) para conocer los detalles. Los pasos de la migración a Bun en sí no han cambiado entre versiones de Astro. Esta guía cubre sitios de Astro estáticos (SSG). Si usas SSR, lee primero la siguiente sección. ### Usuarios de SSR: una advertencia importante Si usas `@astrojs/cloudflare` para el renderizado del lado del servidor con Astro 6+, Cloudflare Pages **ya no es compatible** con despliegues SSR. Desde `@astrojs/cloudflare` v13, solo Cloudflare Workers es compatible con el renderizado bajo demanda. Los sitios estáticos no se ven afectados por este cambio. Si usas `@astrojs/cloudflare` para SSR con Astro 6+, debes desplegar en Cloudflare Workers, no en Pages. Los sitios estáticos no se ven afectados. ## 1. Instala Bun ```sh curl -fsSL https://bun.sh/install | bash ``` ```sh brew install bun ``` ```powershell powershell -c "irm bun.sh/install.ps1 | iex" ``` ```sh npm install -g bun ``` Después de instalarlo, verifica que funciona: ```sh bun --version ``` Deberías ver `1.3.x` o superior. Si obtienes `command not found`, reinicia tu terminal o ejecuta `source ~/.bashrc` / `source ~/.zshrc`. Ejecuta `bun --version`. Deberías ver 1.3.x o superior. Si está por debajo de 1.1.x, conviene actualizar para mantener la compatibilidad con la optimización de imágenes de Sharp. Puedes consultar [Bun vs NPM, Yarn, PNPM y otros](/es/gestor-paquetes-bun/) para una comparación detallada de Bun frente a otros gestores de paquetes. ## 2. Elimina los archivos de bloqueo existentes Elimina el lockfile del gestor de paquetes que estuvieras usando antes: ```sh # Si usabas npm: rm package-lock.json # Si usabas pnpm: rm pnpm-lock.yaml # Si usabas Yarn: rm yarn.lock ``` Bun crea su propio lockfile: `bun.lock` (formato de texto, predeterminado desde ~v1.2) o `bun.lockb` (binario). Se genera en el próximo `bun install`. Cloudflare Pages ejecuta `bun install --frozen-lockfile` de forma predeterminada. Si `bun.lock` o `bun.lockb` no están confirmados en tu repositorio, la compilación fallará con un error de discrepancia del lockfile. ## 3. Instala las dependencias con Bun Ejecuta `bun install` para instalar las dependencias de tu proyecto: ```sh bun install ``` Esto lee tu `package.json` y descarga los paquetes mucho más rápido que npm (normalmente de 10 a 30 veces en instalaciones limpias). La mayor ventaja es el tiempo de instalación de dependencias en CI/CD. Sharp, la biblioteca de optimización de imágenes de Astro, funciona con Bun de forma nativa. Estuvo rota en 2023-2024, pero se corrigió desde Bun ~1.1.x. No hacen falta workarounds. Si más adelante necesitas actualizar los paquetes a sus últimas versiones, mira cómo [actualizar paquetes con Bun](/es/actualizar-paquetes-bun/). ## 4. Prueba tu proyecto de Astro en local Inicia el servidor de desarrollo para asegurarte de que todo funciona: ```sh bun run dev ``` Abre `http://localhost:4321` y verifica que tus páginas cargan correctamente. Después, prueba la compilación de producción: ```sh bun run build ``` El directorio `dist/` debería crearse sin errores. ### Entendiendo el flag `--bun` Hay una distinción que la mayoría de las guías omiten: - `bun run dev` / `bun run build` ejecuta Astro a través de la **capa de compatibilidad con Node.js** de Bun. Es estable y está recomendado para la mayoría de los proyectos. - `bun run --bun dev` / `bun run --bun build` ejecuta Astro usando el **runtime real de Bun**. Es más rápido, pero algunas integraciones pueden tener asperezas. Empieza con `bun run build` (modo de compatibilidad con Node) para mayor estabilidad. Si tu proyecto compila sin problemas y quieres más velocidad, prueba `bun run --bun build`. Si te encuentras con `ERR_HTTP_SOCKET_ASSIGNED` u otros errores específicos de Node, vuelve al modo de compatibilidad. Seguirá siendo más rápido que npm. Si quieres exprimir más velocidad en tus compilaciones, consulta las guías sobre el [rendimiento de compilación de Astro 7](/es/astro-7-compilaciones-mas-rapidas/) y cómo [optimizar la velocidad de compilación de Astro](/es/astro-ssg-optimizacion-build/). ## 5. Configura Cloudflare Pages para Bun Inicia sesión en el panel de Cloudflare y ve a la configuración de tu proyecto. Tendrás que actualizar el comando de compilación y, opcionalmente, fijar tu versión de Bun. Si aún no has configurado Cloudflare Pages, mira primero cómo [desplegar un sitio de Astro en Cloudflare Pages](/es/desplegar-astrojs-cloudflare/). ### Actualiza el comando de compilación Cambia el comando de compilación de Cloudflare Pages a: ``` bun run build ``` ``` bun run --bun build ``` El recomendado `bun run build` usa la capa de compatibilidad con Node.js de Bun, que es estable y más rápida que npm. La variante `--bun` usa el runtime nativo de Bun. Es más rápida, pero puede no funcionar con todas las integraciones. Empieza con la opción recomendada. ### Fija tu versión de Bun con BUN_VERSION En Cloudflare Dashboard → Settings → Environment variables, añade: ``` BUN_VERSION=1.3.14 ``` Sustituye `1.3.14` por la última versión estable de Bun. Fijar la versión evita roturas inesperadas cuando Cloudflare actualiza la versión predeterminada de Bun en su imagen de compilación. Configurar `BUN_VERSION=latest` provoca un error 403 durante la compilación. El script de instalación de Bun sufre problemas de rate-limiting al obtener la lista de versiones a través de la imagen de compilación de Cloudflare (que usa `asdf` internamente). Fija siempre una versión concreta como `1.3.14`. ### Versiones del sistema de compilación de Cloudflare Pages (v2 frente a v3) Cloudflare Pages tiene tres versiones del sistema de compilación: - **v3**: predeterminada para proyectos nuevos. Bun 1.2.15, Node 22.16.0, Ubuntu 22.04.2. - **v2**: Bun 1.1.33 y Node 18.17.1 por defecto. Migrará automáticamente a v3 para febrero de 2027. - **v1**: obsoleta. Migrará automáticamente a v3 para septiembre de 2026. Los proyectos nuevos usan v3 por defecto. Si estás en v1 o v2, considera actualizar en Cloudflare Dashboard, Pages, Settings. v1 no tiene Bun preinstalado, así que necesitas v2 o v3. El plan gratuito de Cloudflare Pages te da 500 compilaciones al mes, 1 compilación simultánea y un límite estricto de 20 minutos por compilación. Las instalaciones más rápidas de Bun ayudan a que los proyectos grandes se mantengan por debajo de ese límite. No hay coste adicional por usar Bun en lugar de Node. ## 6. Despliega en Cloudflare Confirma tus cambios y súbelos a tu repositorio Git: ```sh git add . git commit -m "Migrate to Bun" git push ``` Cloudflare detectará el push y empezará a compilar con la nueva configuración de Bun. Puedes seguir el progreso en Cloudflare Dashboard → Pages → tu proyecto → Deployments. ## 7. Verifica el despliegue No des por hecho que funcionó. Comprueba lo siguiente: Cómo verificarlo: 1. **Log de compilación**: Cloudflare Dashboard → Pages → Deployments → haz clic en la última compilación → lee el log. Busca `bun install vX.X.X` cerca del principio. 2. **Revisión del sitio**: visita tu URL de producción y navega por varias páginas. 3. **Revisión de la consola**: abre las DevTools del navegador → pestaña Console. Busca errores o advertencias que no estuvieran antes. ```sh # Comprobación HTTP rápida desde tu terminal: curl -I https://your-site.pages.dev ``` Deberías obtener una respuesta `200 OK`. ## Resolución de problemas habituales `bun install` puede quedarse colgado de forma intermitente en Cloudflare Pages. Es un problema conocido. **Solución**: define `SKIP_DEPENDENCY_INSTALL=true` como variable de entorno en Cloudflare Dashboard y luego cambia tu comando de compilación para instalar Bun manualmente con npm: ```bash npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build ``` Esto evita el Bun preinstalado e instala una copia nueva durante la compilación. Configurar `BUN_VERSION=latest` falla porque el script de instalación de Bun no puede obtener la lista de versiones a través de la imagen de compilación de Cloudflare, basada en `asdf`. **Solución**: fija una versión concreta de Bun: ``` BUN_VERSION=1.3.14 ``` Probablemente tu proyecto de Cloudflare Pages esté en el sistema de compilación v1, que no tiene Bun preinstalado. **Solución**: ve a Cloudflare Dashboard → Pages → Settings y actualiza al sistema de compilación v2 o v3. En 2023-2024, Sharp (el optimizador de imágenes de Astro) no funcionaba con Bun. Esto se resolvió desde Bun ~1.1.x. **Solución**: asegúrate de ejecutar Bun 1.1.x o superior. Si estás en una versión anterior, actualiza la variable de entorno `BUN_VERSION`. Probablemente estés usando el flag `--bun`, que ejecuta Astro a través del runtime nativo de Bun en lugar del modo de compatibilidad con Node.js. Algunas integraciones no funcionan del todo bien con el Bun nativo. **Solución**: quita el flag `--bun`. Usa `bun run build` en lugar de `bun run --bun build`. Seguirás teniendo los tiempos de instalación más rápidos de Bun. Cloudflare Pages ejecuta `bun install --frozen-lockfile` de forma predeterminada. Si tu archivo `bun.lock` o `bun.lockb` no está confirmado, la compilación falla. **Solución**: ejecuta `bun install` en local y luego confirma el lockfile: ```sh git add bun.lock git commit -m "Add Bun lockfile" git push ``` Si el Bun preinstalado es demasiado antiguo y `BUN_VERSION` no admite la versión que necesitas, usa este workaround. Define `SKIP_DEPENDENCY_INSTALL=true` como variable de entorno y luego usa este comando de compilación: ```bash npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build ``` Esto instala un Bun nuevo durante la compilación. Si tu compilación supera el tiempo límite, las instalaciones más rápidas de Bun pueden ayudar. El límite de 20 minutos por compilación es estricto. Mira cómo [optimizar la velocidad de compilación de Astro](/es/astro-ssg-optimizacion-build/) para más consejos. ## Cuándo no migrar a Bun - Usas **SSR de Astro con `@astrojs/cloudflare`** en Astro 6+. Cloudflare Pages ya no es compatible con SSR, solo Workers. Esta guía no te servirá. - Dependes de **paquetes específicos de Node.js** que no se han probado con Bun. - Usas **plugins de Vite que dependen de aspectos internos de Node.js**. Estos pueden romperse con el flag `--bun`. - Tu proyecto **ya compila y despliega bien** con npm o pnpm. Valora si el esfuerzo de la migración merece la pena para tu caso de uso. ## Conclusión Bun en Cloudflare Pages es un runtime compatible con un sistema de compilación maduro (v3) y un fijado de versiones adecuado. La migración es un esfuerzo único: cambia tu lockfile, instala las dependencias con `bun install`, actualiza el comando de compilación a `bun run build` y fija `BUN_VERSION` en Cloudflare Dashboard. Obtienes instalaciones de dependencias más rápidas, compilaciones más rápidas en proyectos con mucha E/S y una experiencia de desarrollo local más sencilla. Si empiezas un proyecto nuevo, puedes [crear un blog gratis con Astro y Cloudflare](/es/crear-blog-astro-gratis/) con Bun desde el primer día. Si estás valorando plataformas de despliegue alternativas para sitios estáticos de Astro, Bunny.net es una opción sólida. Aquí tienes cómo [desplegar Astro en Bunny.net](/es/desplegar-astro-bunny-net/).