¿Falló el build de Astro? Resuelve estas 7 causas comunes en 5 minutos

Errores rojos por toda la terminal. En local todo va bien: npm run dev vuela, los componentes se renderizan perfectamente y las rutas funcionan. Pero al ejecutar astro build, todo explota.

Los fallos de build en Astro son de los problemas que más frustran a quien desarrolla frontend. La diferencia entre el entorno local y el build de producción desconcierta. Los mensajes de error suelen ocupar decenas de líneas, llenos de jerga técnica, y no siempre queda claro por dónde empezar.

Este artículo resume lo aprendido: cómo localizar la mayoría de los problemas en 5 minutos, 7 escenarios de fallo de build más frecuentes con soluciones, trampas específicas de Vercel, Cloudflare Pages y GitHub Pages, y buenas prácticas preventivas para evitar repetir los mismos errores. El 90 % de los fallos de build encajan en estas 7 causas habituales.

Referencia rápida: tabla de mensajes de error

Primero, una tabla de referencia para consultar al instante:

1. Marco de diagnóstico rápido: localizar el problema en 5 minutos

3 puntos clave para entender el mensaje de error

Mucha gente entra en pánico al ver un error, pero la respuesta suele estar en el propio mensaje. Estos 3 puntos te ayudan a interpretarlo rápido:

1. Identificar el tipo de error

Mira la primera línea o las palabras clave:

• SyntaxError: problema de sintaxis en el código
• ModuleNotFoundError o Cannot find module: dependencia no encontrada
• ValidationError: fallo de validación de datos (normalmente frontmatter de Content Collections)
• ENOENT: archivo o directorio inexistente
• is not defined (document/window): acceso a APIs del navegador durante el renderizado en servidor

Por ejemplo, si ves SyntaxError: Unexpected token 'with', casi seguro la versión de Node.js es demasiado baja.

2. Localizar la posición del error

Busca información como esta:

at /path/to/your/file.astro:23:5

Te indica qué archivo y en qué línea falla. No te distraigas con rutas de node_modules en medio: lo importante es encontrar la ruta de tu propio código.

A veces el error no está en tu código, sino en una dependencia. En ese caso, mira la parte superior del stack trace; suele haber pistas del tipo Error: xxx caused by.

3. Entender el contexto del error

Fíjate en qué fase aparece:

• Building for production... → error en la fase de build
• Rendering... → error en la fase de renderizado de páginas
• vite v5.0.0 building for production... → error en la capa de build de Vite

Los errores en la fase de build suelen ser de configuración o dependencias; los de renderizado, más de lógica de código.

Método de diagnóstico en 5 pasos

Ya sabes cómo leer el mensaje de error. Sigue estos 5 pasos y la mayoría de los problemas quedarán localizados:

Paso 1: comprobar la versión de Node.js

node -v

Astro requiere Node.js 18.17.1+ o 20.3.0+. Si tu versión es inferior, actualiza. He visto a mucha gente atascarse aquí porque varias plataformas de despliegue usan Node antiguo por defecto.

Si usas nvm en local, puedes cambiar así:

nvm use 20

Paso 2: comprobar que las dependencias están bien instaladas

npm list  # o pnpm list

Busca avisos como UNMET DEPENDENCY o missing. Si aparecen, faltan dependencias.

También compara las fechas de modificación de package.json y package-lock.json. Si el lock file es antiguo, las dependencias pueden estar desincronizadas.

Paso 3: limpiar caché y volver a construir

Es directo y muy efectivo. Ante un error raro, lo primero que hago es limpiar caché:

# Eliminar todos los artefactos de build y dependencias
rm -rf node_modules .astro dist
# Reinstalar
npm install
# Intentar el build de nuevo
npm run build

Al menos el 30 % de los problemas se resuelve así. La contaminación de caché o versiones inconsistentes de dependencias es muy habitual.

Paso 4: revisar los archivos modificados recientemente

Piensa: ¿qué cambiaste desde el último build exitoso? ¿Un componente nuevo? ¿Configuración? ¿Una dependencia nueva?

Mira los cambios recientes con git:

git diff HEAD

Muchas veces el problema está en el último commit o en los dos anteriores. Puedes comentar temporalmente el código nuevo y ver si el build pasa; así localizas el origen rápido.

Paso 5: comparar el entorno local con el de CI

Si el build funciona en local pero falla en CI/CD o en la plataforma de despliegue, el problema es la diferencia de entorno. Revisa sobre todo:

• Versión de Node: ¿es la misma en local y en producción?
• Gestor de paquetes: ¿npm, pnpm o yarn? ¿Misma versión?
• Variables de entorno: ¿están todas configuradas en producción?
• Versiones de dependencias: ¿subiste el lock file? ¿Las versiones instaladas en producción coinciden con las locales?

Una vez usé Node 20 en local y Vercel Node 18 por defecto. Llamé a una API solo disponible en Node 20 y en producción falló. Lo resolví especificando la versión de Node en los ajustes del proyecto de Vercel.

2. Las 7 causas más frecuentes de fallo de build

Causa 1: versión de Node.js incompatible

Mensaje de error típico:

SyntaxError: Unexpected token 'with'

o

error: Cannot use import statement outside a module

Causa raíz:

Astro necesita Node.js 18.17.1 o superior (o 20.3.0+). Muchos fallos de build empiezan por una versión demasiado baja.

Suele ocurrir por dos motivos:

1. Actualizaste Node en local, pero la plataforma de despliegue sigue con una versión antigua
2. En el equipo, cada desarrollador usa una versión distinta de Node

Solución:

Entorno local:

Si usas nvm, cambiar es sencillo:

nvm install 20
nvm use 20

Configuración en la plataforma de despliegue:

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

Empezar →Anuncio

Cada plataforma tiene su método:

Vercel:
En Project Settings → General → Node.js Version, elige 20.x

Cloudflare Pages:
Crea un archivo .nvmrc en la raíz del proyecto:

20

Netlify:
Crea netlify.toml en la raíz:

[build.environment]
  NODE_VERSION = "20"

Medida preventiva:

Añade esto en package.json para dejar clara la versión requerida:

{
  "engines": {
    "node": ">=18.17.1"
  }
}

Así, si alguien usa una versión baja, npm install mostrará una advertencia.

Causa 2: conflictos de dependencias o problemas con el lock file

Mensaje de error típico:

Error: Cannot find module 'astro'
ERR_MODULE_NOT_FOUND

o algo más extraño:

X [ERROR] The build was canceled

Escenarios habituales:

He visto este tipo de problemas varias veces, normalmente por:

1. Problemas de compatibilidad del gestor de paquetes

Después de Astro 4.11.2 hubo ajustes en el soporte de Bun y pnpm; algunos proyectos dejaron de instalar dependencias de golpe. Me pasó al pasar de 4.11.1 a 4.11.2: pnpm falló de repente hasta que el equipo de Astro lo corrigió.

2. Lock file y node_modules desincronizados

Cambiaste package.json pero no actualizaste el lock file, o al revés: hiciste pull del lock de otro y no reinstalaste dependencias en local.

3. Paquetes de terceros problemáticos por naturaleza

Algunos paquetes fallan con frecuencia en Astro, por ejemplo:

• astro-compress: muchos reportan que provoca fallos de build
• @supercharge/strings: se ha visto el error is not a function
• nodejs-mysql: mejor sustituirlo por mysql2, con mejor compatibilidad

Solución:

El trío estándar:

# 1. Eliminar dependencias y caché
rm -rf node_modules .astro dist package-lock.json
# O si usas pnpm:
rm -rf node_modules .astro dist pnpm-lock.yaml

# 2. Limpiar caché del gestor de paquetes
npm cache clean --force
# o pnpm store prune

# 3. Reinstalar
npm install
# En CI, usa esto para alinear dependencias y lock file:
npm ci

Si aún falla, revisa la configuración:

Los usuarios de pnpm a veces necesitan ajustar .npmrc:

shamefully-hoist=true
public-hoist-pattern[]=*astro*

Método de aislamiento mínimo:

Si sospechas de una dependencia concreta:

1. Crea un proyecto Astro nuevo:

npm create astro@latest minimal-test -- --template minimal

2. Añade la dependencia problemática y comprueba si se reproduce

3. Si se reproduce, busca en GitHub Issues si alguien reportó lo mismo

Yo usé este método para confirmar que el problema era astro-compress y acabé cambiando a otra solución de optimización de imágenes.

Causa 3: fallo de validación del formato de Content Collections

Mensaje de error típico:

Error: blog → post.md frontmatter does not match collection schema.
"date" must be a valid date

o:

MarkdownContentSchemaValidationError: Content entry frontmatter does not match schema
"title" is required

Causa raíz:

Astro 2.0 introdujo Content Collections y valida el frontmatter de Markdown con Zod. Es muy útil para tipado seguro, pero si el frontmatter no cumple el esquema, el build falla.

Al principio yo también tropecé. Tenía artículos antiguos con frontmatter irregular: fechas como 2024-01-01 o 2024/01/01, o campos omitidos. Al activar Content Collections, todo empezó a fallar.

Errores frecuentes:

1. Campos obligatorios ausentes

Si el schema exige title y un Markdown no lo tiene:

---
# Olvidaste el title
date: 2024-01-01
---

2. Tipo de campo incorrecto

Lo más habitual son las fechas:

---
title: "My Post"
date: 2024/01/01  # Debería ser 2024-01-01
---

O un array escrito como string:

---
tags: javascript  # Debería ser [javascript] o ["javascript"]
---

3. Nombre de campo mal escrito

Si el schema define description y tú escribes desc, Astro no lo reconoce.

Solución:

Paso 1: revisar la definición del schema

Abre src/content/config.ts y mira cómo está definido:

import { z, defineCollection } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

Paso 2: corregir el frontmatter según el mensaje de error

El error indica qué archivo y qué campo fallan. Por ejemplo:

blog → my-post.md frontmatter does not match collection schema.
"date" must be a valid date

Corrige la fecha en src/content/blog/my-post.md:

---
title: "Mi artículo"
date: 2024-01-01  # Formato YYYY-MM-DD
tags: ["astro", "blog"]
---

Paso 3: usar .passthrough() para artículos antiguos irregulares

Si tienes muchos artículos históricos, puedes relajar la validación:

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),  // Conversión automática
    tags: z.array(z.string()).optional().default([]),
  }).passthrough(),  // Permite campos extra
});

.passthrough() significa que los campos no definidos en el schema no provocan error.

Paso 4: reiniciar el servidor de desarrollo

Tras modificar el schema, reinicia el dev server:

# Detener (Ctrl+C)
# Volver a arrancar
npm run dev

O, con el dev server en marcha, pulsa s + enter para sincronizar la capa de contenido.

Causa 4: configuración incorrecta de variables de entorno

Escenario típico:

npm run dev y npm run build funcionan en local, pero al desplegar en Vercel/Cloudflare:

• La página se muestra incompleta
• Algunas funciones fallan (comentarios, llamadas a API)
• El build pasa pero hay errores en ejecución

Problemas habituales:

1. Variables de entorno no configuradas en la plataforma

Tienes .env en local, pero .gitignore lo excluye (correcto: no debes subir secretos). El problema es que la plataforma de despliegue no conoce esos valores.

2. Uso incorrecto del prefijo PUBLIC_

Astro tiene una regla especial:

• Las variables accesibles en el cliente deben empezar por PUBLIC_
• Las variables solo de servidor no llevan prefijo

Si en código de cliente usas una variable sin PUBLIC_, en el build será undefined.

Ejemplo:

// .env
API_KEY=abc123
PUBLIC_SITE_URL=https://example.com

// Código de cliente
const apiKey = import.meta.env.API_KEY;  // ❌ undefined
const siteUrl = import.meta.env.PUBLIC_SITE_URL;  // ✅ correcto

Solución:

Configuración por plataforma:

Vercel:

1. Proyecto → Settings → Environment Variables
2. Añade variables y elige el entorno (Production/Preview/Development)
3. Vuelve a desplegar

Cloudflare Pages:

1. Proyecto → Settings → Environment variables
2. Configura Production y Preview por separado
3. Lanza un nuevo build

Netlify:

1. Site settings → Environment variables
2. Añade variables
3. Dispara un nuevo despliegue

Uso correcto de variables de entorno:

// astro.config.mjs
export default defineConfig({
  // Aquí puedes usar cualquier variable de entorno
  site: import.meta.env.PUBLIC_SITE_URL,
});

// src/pages/index.astro
---
// Código de servidor: cualquier variable
const apiKey = import.meta.env.API_KEY;
const response = await fetch(`https://api.example.com?key=${apiKey}`);
---

<script>
  // Código de cliente: solo variables con prefijo PUBLIC_
  const siteUrl = import.meta.env.PUBLIC_SITE_URL;
  console.log(siteUrl);  // Funciona

  const apiKey = import.meta.env.API_KEY;
  console.log(apiKey);  // undefined
</script>

Aviso de seguridad:

No pongas información sensible (claves API, contraseñas de base de datos) en variables con prefijo PUBLIC_. Esos valores se inyectan en el JS empaquetado y cualquiera puede verlos.

Si necesitas llamar a una API desde el cliente, mejor hazlo a través de tu propio backend en lugar de exponer la clave API.

Causa 5: errores en la configuración

Mensaje de error típico:

A veces no hay un error claro: el build se queda colgado, entra en bucle o aparece un error raro de Vite.

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

Obtener 15% dto. →Anuncio

Puntos problemáticos frecuentes:

1. base path mal configurado (despliegue en GitHub Pages)

La URL de GitHub Pages es https://username.github.io/repo-name/. Si astro.config.mjs no define base, las rutas de recursos devuelven 404.

Configuración incorrecta:

export default defineConfig({
  site: 'https://username.github.io/my-blog/',
  // Olvidaste configurar base
});

Configuración correcta:

export default defineConfig({
  site: 'https://username.github.io',
  base: '/my-blog',  // Nombre del repositorio como base path
});

2. Conflictos entre integraciones

Se ha reportado conflicto entre la integración de Svelte y content/config.ts, provocando The build was canceled.

Una vez tuve varios plugins de optimización de imágenes a la vez; entraban en conflicto y quitando uno se resolvió.

Solución:

Revisar base path:

Si despliegas en un subpath (como GitHub Pages), configura base:

// astro.config.mjs
export default defineConfig({
  site: 'https://yourdomain.com',
  base: process.env.BASE_PATH || '/',  // / en local, ruta real en despliegue
});

Y en CI define la variable de entorno:

# .github/workflows/deploy.yml
env:
  BASE_PATH: /my-blog

Aislar conflictos de integraciones:

Si sospechas de una integración, coméntalas una a una:

// astro.config.mjs
export default defineConfig({
  integrations: [
    // react(),
    // tailwind(),
    // sitemap(),
  ],
});

Empieza con la configuración mínima y ve añadiendo integraciones hasta encontrar la que falla.

Causa 6: paquetes de terceros incompatibles con SSG/SSR

Mensaje de error típico:

ReferenceError: document is not defined
ReferenceError: window is not defined

Causa raíz:

Astro construye páginas por defecto en el servidor (entorno Node.js), pero algunos paquetes npm están pensados para el navegador y acceden a document, window, etc. En el build en servidor esas APIs no existen y falla.

La primera vez me pasó con una librería de gráficos. En dev se veía bien porque el modo desarrollo renderiza en el navegador. Al hacer build, apareció document is not defined.

Paquetes problemáticos habituales:

• Librerías de UI que manipulan el DOM
• Librerías de detección de navegador o dispositivo
• Plugins jQuery antiguos
• Paquetes que ejecutan window.xxx en el nivel superior del módulo

Solución:

Opción 1: directiva client:only

Indica a Astro que el componente solo se renderice en el cliente:

---
import ProblematicComponent from './ProblematicComponent';
---

<ProblematicComponent client:only="react" />

Tras client:only debes indicar el framework (react/vue/svelte, etc.).

Opción 2: importación dinámica

Carga el paquete solo en el cliente:

---
// No importar en el servidor
---

<script>
  // Importación dinámica en el cliente
  const { default: MyLibrary } = await import('problematic-package');
  const instance = new MyLibrary();
</script>

Opción 3: importación condicional

Comprueba el entorno antes de usar:

let myLib;
if (typeof window !== 'undefined') {
  myLib = await import('problematic-package');
}

Opción 4: cambiar a un paquete compatible

A veces lo más simple es sustituir el paquete:

• nodejs-mysql → mysql2
• Algunas librerías de gráficos antiguas → chart.js (más amigable con SSR)
• Plugins jQuery → JS nativo o componentes de frameworks modernos

Mi recomendación:

Antes de elegir un paquete de terceros, revisa si su documentación menciona soporte SSR/SSG. Muchas librerías populares lo indican explícitamente. Si dice “works with Next.js” o “SSR compatible”, normalmente también funcionará en Astro.

Causa 7: breaking changes al actualizar Astro

Escenario típico:

Tras actualizar a Astro 5 (u otra versión mayor), un proyecto que antes compilaba de repente:

• Se queda colgado en el build
• Muestra errores raros de resolución de módulos
• Deja de estar disponible alguna API

Problemas habituales:

1. Cambios en la resolución de módulos CommonJS

Astro 5 modificó parte de la lógica de resolución; paquetes CommonJS que antes funcionaban pueden fallar.

2. APIs obsoletas o modificadas

Cada versión mayor depreca APIs antiguas. Algunos métodos Astro.xxx pueden haberse renombrado o eliminado.

3. Integraciones incompatibles con la nueva versión

Tras actualizar Astro, integraciones oficiales o de terceros también deben actualizarse a la versión correspondiente.

Estrategia de solución:

Actualiza paso a paso, sin saltar versiones:

Si quieres pasar de Astro 3 a 5, no lo hagas de un salto. Sube primero a 4, verifica, y luego a 5. Así localizas el problema con más facilidad.

# Enfoque incorrecto
npm install astro@latest

# Enfoque recomendado
npm install astro@^4.0.0
# Tras verificar
npm install astro@^5.0.0

Usa la herramienta de actualización de Astro CLI:

Astro ofrece una herramienta que ayuda con breaking changes habituales:

npx @astrojs/upgrade

Esta herramienta:

• Analiza tu proyecto
• Sugiere dependencias a actualizar
• Modifica automáticamente parte del código (por ejemplo, llamadas a APIs obsoletas)

Actualiza también las integraciones:

Tras actualizar Astro, no olvides las integraciones oficiales:

npm install @astrojs/react@latest @astrojs/tailwind@latest @astrojs/sitemap@latest

A veces el build falla porque Astro está en la 5 pero las integraciones siguen en la era de Astro 4.

3. Problemas específicos por plataforma de despliegue

Después de las 7 causas generales, conviene conocer las trampas propias de cada plataforma.

Problemas al desplegar en Vercel

Problema típico 1: timeout de build

El plan gratuito de Vercel limita el tiempo de build. En proyectos grandes o con instalación lenta de dependencias, puede agotarse el tiempo.

Soluciones:

• Revisa package.json y elimina dependencias innecesarias
• Usa pnpm en lugar de npm para instalar más rápido
• Valora el plan Pro si el presupuesto lo permite

Problema típico 2: directorio de salida mal configurado

Vercel necesita saber dónde están los artefactos. Astro genera dist por defecto, pero si cambias la configuración, Vercel puede no encontrarlos.

Configuración correcta:

• Build Command: npm run build o astro build
• Output Directory: dist (valor por defecto de Astro)
• Install Command: npm install

Si usas pnpm:

• Install Command: pnpm install

Problemas al desplegar en Cloudflare Pages

Problema típico 1: versión de Node.js demasiado baja

Cloudflare Pages puede usar una versión de Node antigua por defecto. Crea .nvmrc en la raíz:

20

O en los ajustes del proyecto:
Settings → Environment variables → NODE_VERSION = 20

Problema típico 2: astro-compress provoca fallos

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Muchos reportan que astro-compress falla en Cloudflare, sobre todo al optimizar imágenes.

Si te pasa:

1. Desinstala astro-compress: npm uninstall astro-compress
2. Elimínalo de astro.config.mjs
3. Usa otra solución, como el componente <Image /> integrado de Astro

Problema típico 3: configuración del comando de build

Configuración de Cloudflare Pages:

• Build command: npm run build
• Build output directory: /dist
• Root directory: / (ajusta si es un monorepo)

El directorio de salida debe llevar / delante.

Problemas al desplegar en GitHub Pages

Problema típico 1: página 404 o en blanco

La causa más habitual es un base path mal configurado.

La URL del repositorio es https://username.github.io/repo-name/; /repo-name/ es el base path.

Debes configurarlo en astro.config.mjs:

export default defineConfig({
  site: 'https://username.github.io',
  base: '/your-repo-name',  // Nombre del repositorio
});

Problema típico 2: estilos perdidos o recursos 404

Si la página carga pero sin estilos, o las imágenes no aparecen, suele ser el mismo problema de base path.

Abre la consola del navegador y revisa las rutas de los recursos. Si pide https://username.github.io/style.css pero debería ser https://username.github.io/repo-name/style.css, falta configurar base.

4. Buenas prácticas preventivas

Ya sabes cómo resolver los problemas. Lo importante es no repetir los mismos errores.

Establecer un flujo de diagnóstico local

Reproducción mínima (minimal reproduction)

Ante un problema, no modifiques el proyecto a ciegas. Crea primero un proyecto de prueba mínimo:

npm create astro@latest test-project -- --template minimal
cd test-project
# Añade solo la parte problemática: código o dependencia

Si se reproduce en el proyecto mínimo, el problema viene de una función o dependencia concreta, no del proyecto entero. El diagnóstico va mucho más rápido.

Aprovecha la consola del navegador y los logs de build

En desarrollo, abre la consola del navegador:

• Pestaña Console: errores de JavaScript
• Pestaña Network: carga de recursos
• Pestaña Sources: depuración de código

Guarda los logs del build:

npm run build > build.log 2>&1

Así puedes revisar el log completo aunque la terminal se haya llenado.

Crea notas personales de errores resueltos

Yo tengo un archivo markdown con errores y soluciones. Formato simple:

## Error: SyntaxError: Unexpected token 'with'

**Escenario**: fallo de despliegue en Vercel
**Causa**: versión de Node demasiado baja
**Solución**: configurar Node 20.x en Vercel
**Fecha**: 2024-11-15

La próxima vez que veas algo parecido, consulta tus notas: a veces lo resuelves en 5 minutos.

Mantenimiento de la salud del proyecto

Actualizar dependencias con regularidad

Cada mes o trimestre revisa actualizaciones:

# Ver dependencias obsoletas
npm outdated

# Actualizar todo (con cautela)
npm update

# O actualizar una a una
npm install astro@latest

No actualices a ciegas, sobre todo en versiones mayores. Lee el CHANGELOG y busca breaking changes.

Automatizar con Dependabot

Crea .github/dependabot.yml en la raíz del repositorio:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5

Dependabot revisa actualizaciones y abre PRs. Solo tienes que revisar y fusionar.

Script de prueba de build

Añade un script en package.json:

{
  "scripts": {
    "build": "astro build",
    "test:build": "npm run build && echo 'Build successful!'"
  }
}

Configurar pre-commit hook

Con husky, ejecuta el build antes de cada commit:

npm install --save-dev husky

# Inicializar husky
npx husky init

# Añadir pre-commit hook
echo "npm run build" > .husky/pre-commit

Cada commit pasa primero por el build. Si falla, no se confirma. Es más lento, pero evita subir código roto.

Herramientas y recursos útiles

Recursos oficiales de Astro:

1. Guía oficial de resolución de problemas: consulta esto primero
2. Referencia de errores: explicación detallada de cada error de Astro
3. Comunidad de Discord: para casos difíciles

Comandos útiles:

# Comprobar que la configuración de Astro es correcta
npx astro check

# Ver información detallada del build
npx astro build --verbose

# Ejecutar en modo depuración
DEBUG=astro:* npm run dev

Recursos de la comunidad:

• Astro GitHub Issues: busca problemas conocidos
• Stack Overflow: etiqueta [astro]
• Foros y blogs de la comunidad: muchos comparten experiencias con errores típicos

Conclusión

Repasemos lo esencial.

El 90 % de los fallos de build de Astro se deben a estas causas:

1. Versión de Node.js incompatible: comprueba que sea ≥18.17.1 o 20.3.0+
2. Problemas de dependencias: limpia caché, reinstala, revisa el lock file
3. Fallo de validación de Content Collections: corrige el formato del frontmatter
4. Variables de entorno mal configuradas: configúralas en la plataforma; respeta el prefijo PUBLIC_
5. Errores de configuración: revisa base path y conflictos de integraciones
6. Paquetes de terceros incompatibles con SSR: usa client:only o importación dinámica
7. Breaking changes al actualizar: consulta la guía de migración y actualiza paso a paso

Recuerda el método de diagnóstico en 5 pasos:

1. Comprobar versión de Node
2. Comprobar instalación de dependencias
3. Limpiar caché y volver a construir
4. Revisar cambios recientes
5. Comparar entorno local y producción

Lo más importante es un enfoque sistemático. No entres en pánico: lee el mensaje, identifica tipo y ubicación, y aplica la solución adecuada.

Cuando empecé con Astro, un error de build podía llevarme horas. Con esta metodología, ahora suelo resolverlo en 5-10 minutos. Espero que este artículo te ahorre parte de ese camino.

Un aviso final: las versiones evolucionan rápido. Este artículo se escribió a finales de 2024, cuando la versión estable reciente de Astro era la 4.x. Si lo lees con Astro 6.0 o 7.0, contrasta con la documentación oficial porque APIs y mensajes de error pueden haber cambiado. El enfoque de diagnóstico sigue siendo válido.

Si encuentras un problema nuevo, compártelo en los comentarios para seguir mejorando esta guía. Guárdala: la próxima vez que falle el build, ábrela y consulta la tabla de referencia.