Der Astro Static Site Build erzeugt einen dist/-Ordner, der alle fertig kompilierten HTML-Seiten, optimierte Assets und statische Dateien für das Deployment enthält. Die genaue Dist Folder Output Structure hängt davon ab, ob Astro im Static- oder Server-Modus läuft – und ob ein Adapter wie @astrojs/node oder @astrojs/cloudflare konfiguriert ist.
Wer mit Astro arbeitet, muss die Build-Output-Struktur verstehen: für CI/CD-Pipelines, Deployment-Konfigurationen und das Debugging von fehlenden Assets. Besonders seit der Cloudflare-Übernahme Anfang 2026 und dem anstehenden Astro 6 Release hat sich die Architektur des Build-Outputs weiterentwickelt. Dieser Artikel erklärt die dist-Ordnerstruktur für Astro 5 und 6 – mit konkreten Beispielen, typischen Fallstricken und Konfigurationsoptionen.
Astro ist seit Januar 2026 Teil von Cloudflare und bleibt als Open-Source-Framework (MIT-Lizenz) für content-getriebene Websites die erste Wahl, wenn Performance und SEO entscheidend sind. Bei Never Code Alone setzen wir Astro neben Sulu CMS für unsere Frontend-Projekte ein und kennen die Build-Struktur aus der täglichen Arbeit.
Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile einer schnellen, sicheren und barrierefreien Webseite. Erfüllen Sie die gesetzlichen Anforderungen und verbessern Sie die Benutzererfahrung Ihrer Webseite. Mit Astro JS können Sie die Ladezeit reduzieren, die Sicherheit maximieren und die SEO-Optimierung verbessern. Kontaktieren Sie uns, um mehr zu erfahren und um Ihre Webseite auf ein neues Level zu heben.
Im Standard-Modus (output: 'static') ohne Adapter erzeugt astro build eine flache Ordnerstruktur im dist/-Verzeichnis. HTML-Dateien werden direkt im Root angelegt und spiegeln die Routing-Struktur aus src/pages/ wider. Alle optimierten Assets – CSS, JavaScript und verarbeitete Bilder – landen im _astro/-Unterordner mit Content-basierten Hashes für Cache-Busting.
dist/
├── index.html
├── about/
│ └── index.html
├── blog/
│ ├── index.html
│ ├── post-1/
│ │ └── index.html
│ └── post-2/
│ └── index.html
├── _astro/
│ ├── index.D4f2k8.css
│ ├── Layout.B7x3m1.css
│ └── hoisted.Ck9pL2.js
├── robots.txt # aus public/
├── favicon.svg # aus public/
└── manifest.webmanifest # aus public/
Wichtig zu verstehen: Dateien aus dem public/-Verzeichnis werden 1:1 in den dist/-Root kopiert – ohne Verarbeitung, ohne Hashing, ohne Optimierung. Das gilt für Fonts, Bilder, robots.txt und andere statische Assets. Alles aus src/ hingegen durchläuft Astros Build-Pipeline: Komponenten werden zu statischem HTML gerendert, CSS wird gebündelt und optimiert, JavaScript wird nur dort eingebunden, wo es durch client:-Direktiven explizit angefordert wird.
Die Hash-Suffixe in den Dateinamen (z.B. .D4f2k8.css) basieren auf dem Dateiinhalt. Ändert sich der Code, ändert sich der Hash – perfekt für aggressives Browser-Caching mit langen Cache-Control-Headern. Das Build-Verzeichnis lässt sich über outDir in der astro.config.mjs anpassen, Standard ist dist/.
Sobald ein Adapter wie @astrojs/node, @astrojs/cloudflare oder @astrojs/netlify konfiguriert ist, ändert sich die Dist-Ordnerstruktur grundlegend. Astro splittet den Output in zwei Unterordner: client/ für statische Assets und server/ für die SSR-Runtime. Das gilt sowohl für output: 'server' als auch – und das überrascht viele Entwickler – für output: 'static' mit konfiguriertem Adapter.
dist/
├── client/
│ ├── _astro/
│ │ ├── component.B3kLm9.js
│ │ └── style.X2nPq4.css
│ ├── favicon.svg
│ └── robots.txt
└── server/
├── entry.mjs # Server Entry-Point
├── manifest_a1b2c3.mjs # SSR-Manifest
├── renderers.mjs # Framework-Renderer
├── chunks/
│ └── _shared.D8kLp2.mjs
└── pages/
├── index.astro.mjs
└── blog/
└── _slug_.astro.mjs
Der server/entry.mjs ist der zentrale Entry-Point, den Node.js oder die jeweilige Runtime ausführt. Das SSR-Manifest enthält die serialisierte Routing-Konfiguration und wird zur Laufzeit deserialisiert, um eingehende Requests den richtigen Seiten zuzuordnen. Prerenderte Seiten liegen als fertige HTML-Dateien im client/-Ordner, dynamische Routen als .mjs-Module im server/pages/-Ordner.
Häufiger Gotcha 2026: Wer einen Adapter konfiguriert hat, aber eigentlich rein statisch bauen will, bekommt trotzdem die client/server-Struktur. Die Lösung: Den Adapter entfernen, wenn kein SSR benötigt wird. Mit Astro 6 und der tiefen Cloudflare-Integration wird dieser Unterschied noch relevanter, da der neue Dev-Server die gleiche Runtime wie die Produktion nutzt – was die Build-Output-Struktur direkt beeinflusst.
Der _astro/-Ordner ist Astros Standard-Verzeichnis für alle verarbeiteten Assets – gebündeltes CSS, JavaScript-Chunks und optimierte Bilder. Der Name beginnt mit Unterstrich, was bei bestimmten Hosting-Plattformen zu Problemen führen kann. GitHub Pages nutzt intern Jekyll, das Ordner mit Unterstrich ignoriert. Die Lösung ist eine leere .nojekyll-Datei im Build-Output, oder man benennt den Assets-Ordner um.
// astro.config.mjs – Assets-Ordner umbenennen
import { defineConfig } from 'astro/config';
export default defineConfig({
build: {
assets: 'assets' // statt _astro
}
});
Für volle Kontrolle über die Dateinamen im Build-Output bietet Astro Zugriff auf Vites Rollup-Konfiguration. Damit lassen sich Entry-Files, Code-Split-Chunks und statische Assets nach eigenem Schema benennen – nützlich für Teams mit bestehenden CDN-Strukturen oder strikten Naming-Konventionen.
// astro.config.mjs – Custom Dateinamen
import { defineConfig } from 'astro/config';
export default defineConfig({
vite: {
build: {
rollupOptions: {
output: {
entryFileNames: 'js/[name]-[hash].js',
chunkFileNames: 'js/chunks/[name]-[hash].js',
assetFileNames: 'static/[name]-[hash][extname]'
}
}
}
}
});
Das Ergebnis ist eine saubere, vorhersagbare Struktur: JavaScript unter dist/js/, CSS und Bilder unter dist/static/. Für CDN-Setups gibt es zusätzlich die assetsPrefix-Option, mit der Asset-URLs auf eine externe Domain zeigen können – etwa https://cdn.example.com/_astro/. Dateien aus public/ sind von diesen Rollup-Optionen nicht betroffen und landen weiterhin direkt im dist-Root.
Mit Astro 6 (Beta seit Januar 2026) hat sich die Build-Architektur weiterentwickelt. Das Astro-Team – seit der Cloudflare-Übernahme Teil von Cloudflare – hat den Development-Server grundlegend überarbeitet und damit auch die Beziehung zwischen Dev- und Prod-Build verändert. Der neue Dev-Server nutzt Vites Environment API und läuft in der gleichen Runtime wie die Produktion. Für Cloudflare-Projekte bedeutet das: astro dev läuft lokal auf workerd, der gleichen Engine wie Cloudflare Workers.
Für den Build-Output ergeben sich daraus mehrere Änderungen in Astro 6: Live Content Collections ermöglichen Runtime-Datenfetching ohne Rebuild, die neue Fonts API generiert optimierte Font-Dateien im Build, und Content Security Policy (CSP) Support fügt automatisch Hashes für Inline-Scripts und -Styles hinzu. Das alles beeinflusst, was im dist/-Ordner landet und wie die Assets referenziert werden.
Wichtige Breaking Changes für den Build: Astro 6 erfordert Node.js 22+, entfernt Astro.glob() und Legacy Content Collections, und aktualisiert auf Zod 4. Wer von Astro 5 migriert, sollte den offiziellen Upgrade Guide prüfen und den Build-Output nach der Migration genau vergleichen – besonders wenn CI/CD-Pipelines auf bestimmte Dateipfade oder -muster reagieren.
Joining Cloudflare allows us to accelerate Astro's development faster and on a much larger scale. Astro will continue to be the best way for developers to build content-driven websites, whether they host on Cloudflare or elsewhere.
In der Praxis wird astro build selten lokal ausgeführt – sondern in CI/CD-Pipelines wie GitHub Actions, GitLab CI oder Docker-basierten Build-Systemen. Die Build-Output-Struktur bestimmt, was deployed wird: Bei Static Output der gesamte dist/-Ordner, bei Server Output typischerweise dist/server/ für die Runtime und dist/client/ für das Asset-Serving.
# GitHub Actions – Astro Static Build
- name: Build Astro
run: npm run build
- name: Deploy to Server
run: rsync -avz dist/ user@server:/var/www/site/
# Docker – Multi-Stage Build
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
Für Caching in der Pipeline gilt: node_modules/ und Astros Cache-Verzeichnis (.astro/) sollten zwischen Builds gecacht werden, um die Build-Zeit zu reduzieren. Der dist/-Ordner selbst sollte nicht gecacht werden – er wird bei jedem Build neu erzeugt. Bei Never Code Alone integrieren wir Astro-Builds in automatisierte Deployment-Pipelines mit Qualitätssicherung durch BackstopJS für visuelle Regressionstests und Knip für Dead-Code-Erkennung.
Ein häufiges Problem bei Deployments: Der dist/-Ordner mit SSR-Adapter ist nicht ohne Weiteres portabel. Absolute Pfade im SSR-Manifest können dazu führen, dass der Build auf einem anderen Server nicht funktioniert, wenn der Pfad abweicht. Dieses bekannte Problem wird in der Astro-Community aktiv diskutiert und sollte bei Docker-basierten Deployments berücksichtigt werden.
Entdeckt die Vorteile von Astro JS Islands für eure Webprojekte. Unsere Experten bieten fundierte Beratung und Schulungen zur effizienten Implementierung dieser leistungsstarken Architektur.
Mehr erfahrenDie Astro Build Output Structure ist klar und vorhersagbar – wenn man die Unterschiede zwischen Static und Server Output kennt. Im Static-Modus landet alles flach im dist/-Ordner mit gehashten Assets unter _astro/. Mit Adapter wird in client/ und server/ gesplittet. Die Konfigurationsoptionen für Asset-Pfade, Dateinamen und CDN-Prefixes geben volle Kontrolle über das Deployment.
Mit Astro 6 und der Cloudflare-Integration wird die Build-Architektur 2026 noch leistungsfähiger: Unified Dev/Prod-Runtime, Live Content Collections und native CSP-Unterstützung sind Features, die den Build-Output direkt beeinflussen. Wer Astro für content-getriebene Websites einsetzt, profitiert von einer Build-Pipeline, die von Haus aus auf Performance und SEO optimiert ist.
Du planst ein Frontend-Projekt mit Astro oder brauchst Unterstützung bei der Integration in eine bestehende CI/CD-Pipeline? Bei Never Code Alone verbinden wir Astro-Frontend-Expertise mit Backend-Know-how aus Sulu CMS und Symfony. Vereinbare eine kostenlose Erstberatung unter roland@nevercodealone.de oder ruf direkt an: +49 176 24747727.
Die wichtigsten Fragen zur Astro Build Output Structure – so wie Entwickler sie 2026 in Suchmaschinen und KI-Assistants stellen.
Im Static-Modus erzeugt astro build einen flachen dist/-Ordner mit HTML-Dateien im Root und gehashten Assets unter _astro/. Dateien aus public/ werden 1:1 kopiert. Mit einem Adapter wird in dist/client/ und dist/server/ gesplittet. Astro 6 bringt zusätzliche Dateien durch die Fonts API und CSP-Hashes.
Der _astro/-Ordner enthält alle durch Astros Build-Pipeline verarbeiteten Assets: gebündeltes CSS, JavaScript-Chunks und optimierte Bilder. Jede Datei erhält einen Content-basierten Hash im Dateinamen für Cache-Busting. Der Ordnername lässt sich über build.assets in der astro.config.mjs anpassen.
Sobald ein Adapter konfiguriert ist, splittet Astro den Build-Output in client/ für statische Assets und server/ für die SSR-Runtime. Das passiert auch bei output: static mit Adapter – ein häufiger Stolperstein. Wer rein statisch bauen will, muss den Adapter entfernen.
Das Build-Verzeichnis wird über outDir in der astro.config.mjs gesteuert (Standard: dist/). Für Custom-Dateinamen gibt es Vites rollupOptions mit entryFileNames, chunkFileNames und assetFileNames. Für CDN-Deployment setzt assetsPrefix die Domain für alle Asset-URLs.
Astro 6 bringt einen überarbeiteten Dev-Server basierend auf Vites Environment API, der Dev und Prod angleicht. Neue Features wie Live Content Collections, die Fonts API und stabiles CSP beeinflussen den Build-Output. Breaking Changes umfassen Node 22+ Pflicht und die Entfernung von Astro.glob().
Bei GitHub Pages muss eine leere .nojekyll-Datei im dist/-Root liegen, da Jekyll Ordner mit Unterstrich ignoriert und _astro/ sonst nicht erreichbar ist. Alternativ benennt man den Assets-Ordner über build.assets um. Für das Deployment selbst wird der gesamte dist/-Ordner ins Repository gepusht oder per GitHub Action deployed.
Alle Dateien aus public/ werden beim Build 1:1 in den dist/-Root kopiert – ohne Verarbeitung, ohne Hashing, ohne Optimierung. Das betrifft robots.txt, favicon.svg, Fonts, manifest.webmanifest und andere statische Assets. CSS und JavaScript sollten besser in src/ liegen, um von Astros Optimierungen zu profitieren.
Astro generiert Content-basierte Hashes als Suffixe in Asset-Dateinamen, zum Beispiel style.X2nPq4.css. Der Hash ändert sich nur wenn sich der Dateiinhalt ändert. Das ermöglicht aggressives Browser-Caching mit langen Cache-Control max-age Headern, da geänderte Dateien automatisch neue URLs erhalten.
Ja, über assetsPrefix in der astro.config.mjs lassen sich Asset-URLs auf eine externe CDN-Domain zeigen, etwa https://cdn.example.com/_astro/. Für granulare Kontrolle akzeptiert assetsPrefix auch ein Objekt mit unterschiedlichen Domains pro Dateityp. Zusätzlich lässt sich der _astro-Ordnername über build.assets ändern.
In CI/CD-Pipelines wird npm run build oder astro build ausgeführt und der dist/-Ordner deployed. Für Caching sollten node_modules/ und .astro/ zwischen Builds persistiert werden. Bei Docker-Deployments eignet sich ein Multi-Stage-Build mit Node.js als Build-Stage und Nginx als Serving-Stage.
Static Output erzeugt nur HTML-Dateien und gehashte Assets – perfekt für Hosting ohne Server-Runtime. Server Output enthält zusätzlich eine entry.mjs als Server-Entry-Point, ein SSR-Manifest und Route-Handler als .mjs-Module. Static ist schneller, Server ermöglicht dynamische Seiten und API-Endpunkte.
Seit Januar 2026 ist Astro Teil von Cloudflare. Der Astro 6 Dev-Server nutzt workerd, Cloudflares JavaScript-Runtime, für Development-Production-Parity. Für den Build-Output bedeutet das bessere Kompatibilität mit Cloudflare Workers und Pages, nativen Zugriff auf KV, R2 und Durable Objects, und optimierte Adapter-Integration.
Entdecken Sie die Accessible Astro Components – barrierefreie UI-Komponenten für Astro, die WCAG-konforme, benutzerfreundliche und moderne Webanwendungen ermöglichen. Ideal für inklusives Design und optimierte User Experience.
Entdecken Sie, wie Astro Images Ihre Website-Performance und SEO-Rankings revolutioniert. Unsere Agentur bietet Ihnen das nötige Know-how für Implementierung und Schulungen. Optimieren Sie jetzt!
Entdeckt, wie Astro JS als innovativer Static Site Generator eure Website-Performance revolutioniert. Lernt die Vorteile für Content-fokussierte Seiten kennen.
Entdeckt die Vorteile von Astro JS Islands für eure Webprojekte. Unsere Experten bieten fundierte Beratung und Schulungen zur effizienten Implementierung dieser leistungsstarken Architektur.
Astro Script Tags richtig einsetzen: Inline-Import, is:inline, Custom Elements und häufige Production-Fehler vermeiden. Best Practices direkt aus den Astro-Docs.
Erfahrt, wie ihr mit der richtigen Anpassung von Zeilenabständen (line-height) und Textabständen eure Webseite barrierefrei macht. Praxisnahe Tipps und WCAG-Konformität für Einsteiger und Profis.
Entdeckt ScrewFast, das vielseitige kostenlose Astro JS Theme für Landingpages. Unsere Agentur bietet Expertise bei der Implementierung und maßgeschneiderte Schulungen.
Vitest 3.0: Schneller JavaScript-Test-Runner mit Vite-Integration. Neue Features, Vorteile und Anwendungen für effizientes Testing in modernen Webprojekten.
