# Cómo funcionan los builds

Source : https://webgune.cloud/es-es/docs/builds-railpack · Mis à jour le 2026-10-27

# Cómo funcionan los builds

Cada despliegue empieza con un **build**: tu código fuente se transforma en una imagen de contenedor, se sube al registry interno de la plataforma, y luego se despliega en el clúster.

## El pipeline de build

1. **Obtención del código**: desde la rama de GitHub seguida (o tu subida manual).
2. **Detección del stack**: el builder automático analiza el repositorio y elige la receta adecuada (Node.js, Python, Go, PHP…).
3. **Construcción de la imagen**: dependencias instaladas, build ejecutado (`next build`, `vite build`…), imagen final optimizada.
4. **Push al registry**: la imagen queda versionada en el registry interno, visible en la pestaña **Registry** del servicio.
5. **Despliegue**: el clúster cambia a la nueva imagen sin interrupción.

## Los dos modos de build

| Modo | Cuándo usarlo |
|------|------------------|
| **Build automático** (por defecto) | La mayoría de los casos, sin configuración |
| **Dockerfile** | Quieres control total sobre la imagen ([guía](/docs/docker-dockerfile)) |

Si hay un `Dockerfile` en la raíz del repositorio, puede usarse en lugar de la detección automática.

## Seguir un build

La pestaña **Despliegues** del servicio lista todos los builds con su estado y sus **logs completos**, conservados incluso una vez terminado el build. Un build en curso puede **cancelarse** en cualquier momento.

## Caché de build

Los builds reutilizan una caché (dependencias, capas de imagen) de una vez a otra: el primer build de un servicio es el más largo, los siguientes reutilizan todo lo que no ha cambiado. Si la caché capturó una dependencia obsoleta, **Rebuild sin caché** en el menú del servicio parte de cero.

## Gestión de dependencias Node

Sea cual sea el gestor de paquetes de tu repositorio, los builds se ejecutan con **npm**. Un `bun.lock`, `pnpm-lock.yaml` o `yarn.lock` se descarta antes del build, y los scripts que llaman a esas herramientas se reescriben a sus equivalentes npm. Todo ello se hace sobre la copia de trabajo, nunca sobre tu repositorio.

Tu `package-lock.json`, en cambio, se **conserva y se usa**: las versiones instaladas son exactamente las que fija. Eso es lo que garantiza que una imagen de producción lleve las mismas dependencias que tu máquina.

Solo se descarta en dos casos, ambos anunciados en los logs del build:

- **está desincronizado de tu `package.json`**, por ejemplo por una dependencia añadida sin regenerar el lock. Un `npm install` seguido de un commit del lock lo resuelve;
- **tu repositorio está gestionado por bun, pnpm o yarn** (su archivo es la referencia, y el `package-lock.json` que queda al lado no está actualizado).

En esos dos casos las dependencias simplemente se vuelven a resolver, y sus versiones pueden entonces diferir de las de tu máquina.

> **¿Un build falla?** Abre los logs del build fallido: el error casi siempre aparece ahí (dependencia faltante, script `build` fallido, versión de runtime). El botón **Diagnosticar con IA** también puede orientarte (ver [Asistente IA](/docs/assistant-ia)).

## Seguir explorando

- [Despliegues y rollback](/docs/deploiements-rollback)
- [El archivo kx712.yml](/docs/kx712-yml): ejecutar tests antes de cada despliegue