# Wie Builds funktionieren

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

# Wie Builds funktionieren

Jedes Deployment beginnt mit einem **Build**: Ihr Quellcode wird in ein Container-Image umgewandelt, in die interne Registry der Plattform gepusht und dann im Cluster deployt.

## Die Build-Pipeline

1. **Code abrufen**, vom verfolgten GitHub-Branch (oder Ihrem Upload).
2. **Stack-Erkennung**: der Auto-Builder analysiert das Repository und wählt das passende Rezept (Node.js, Python, Go, PHP…).
3. **Image-Erstellung**: Abhängigkeiten installiert, Build ausgeführt (`next build`, `vite build`…), optimiertes finales Image.
4. **Push in die Registry**: das Image wird versioniert in der internen Registry, sichtbar im Tab **Registry** des Dienstes.
5. **Deployment**: der Cluster wechselt ohne Unterbrechung zum neuen Image.

## Die zwei Build-Modi

| Modus | Wann verwenden |
|------|------------------|
| **Auto-Build** (Standard) | Die meisten Fälle, keine Konfiguration nötig |
| **Dockerfile** | Sie möchten volle Kontrolle über das Image ([Anleitung](/docs/docker-dockerfile)) |

Wenn ein `Dockerfile` im Wurzelverzeichnis des Repositories vorhanden ist, kann es anstelle der automatischen Erkennung verwendet werden.

## Einen Build verfolgen

Der Tab **Deployments** des Dienstes listet alle Builds mit ihrem Status und ihren **vollständigen Logs**, die auch nach Abschluss des Builds erhalten bleiben. Ein laufender Build kann jederzeit **abgebrochen** werden.

## Build-Cache

Builds nutzen von einem Lauf zum nächsten einen Cache (Abhängigkeiten, Image-Layer) wieder: der erste Build eines Dienstes dauert am längsten, die folgenden verwenden alles Unveränderte erneut. Wenn der Cache eine veraltete Abhängigkeit erfasst hat, startet **Rebuild ohne Cache** im Menü des Dienstes komplett neu.

## Umgang mit Node-Abhängigkeiten

Unabhängig vom Paketmanager Ihres Repositorys laufen Builds mit **npm**. Eine `bun.lock`, `pnpm-lock.yaml` oder `yarn.lock` wird vor dem Build beiseitegelegt, und Skripte, die diese Werkzeuge aufrufen, werden auf ihre npm-Entsprechungen umgeschrieben. Das alles geschieht auf der Arbeitskopie, niemals auf Ihrem Repository.

Ihre `package-lock.json` hingegen wird **behalten und verwendet**: die installierten Versionen sind genau die, die sie festschreibt. Das garantiert, dass ein Produktions-Image dieselben Abhängigkeiten mitbringt wie Ihr Rechner.

Sie wird nur in zwei Fällen beiseitegelegt, beide in den Build-Logs angekündigt:

- **sie ist nicht mehr mit Ihrer `package.json` synchron**, etwa weil eine Abhängigkeit ohne Neuerzeugung der Lock-Datei hinzugefügt wurde. Ein `npm install` und das Committen der Lock-Datei klärt das;
- **Ihr Repository wird mit bun, pnpm oder yarn verwaltet** (deren Datei ist maßgeblich, die daneben liegende `package-lock.json` ist nicht aktuell).

In diesen beiden Fällen werden die Abhängigkeiten schlicht neu aufgelöst, und ihre Versionen können dann von denen auf Ihrem Rechner abweichen.

> **Ein Build schlägt fehl?** Öffnen Sie die Logs des fehlerhaften Builds: der Fehler steht dort fast immer (fehlende Abhängigkeit, fehlgeschlagenes `build`-Skript, Runtime-Version). Der Button **Mit KI diagnostizieren** kann Sie ebenfalls weiterleiten (siehe [KI-Assistent](/docs/assistant-ia)).

## Weiterführend

- [Deployments und Rollback](/docs/deploiements-rollback)
- [Die Datei kx712.yml](/docs/kx712-yml): Tests vor jedem Deployment ausführen