Astro auf GitHub Pages zeigt 404 oder kein CSS, so behebt ihr den base Fehler

Lokal sieht die Seite perfekt aus. Nach dem Deploy auf GitHub Pages ist sie plötzlich nackt. Kein CSS, keine Bilder, und jeder Klick führt auf eine 404. Dieser Astro GitHub Pages 404 Fehler hat fast immer dieselbe Ursache. Astro weiß nicht, dass eure Seite in einem Unterordner liegt. Hier steht, wie ihr das in wenigen Minuten behebt und dauerhaft verhindert.

Woran ihr den base Fehler erkennt

• Die Startseite lädt, aber ohne Styles.
• Bilder und Icons fehlen oder zeigen ein kaputtes Symbol.
• Links auf Unterseiten führen auf die 404 Seite von GitHub.
• In den Entwicklertools des Browsers stehen viele Fehler 404 für CSS und JavaScript Dateien.
• Lokal mit npm run dev funktioniert alles.

Treffen mehrere Punkte zu, liegt es mit hoher Wahrscheinlichkeit an site und base.

Warum Astro auf GitHub Pages ins Leere zeigt

Ohne eigene Domain liegt eure Seite nicht im Hauptverzeichnis. Die Adresse ist https://name.github.io/repo-name/. Astro baut aber standardmäßig alle Pfade so, als läge die Seite direkt unter /. Der Browser sucht das CSS also unter name.github.io/_astro/... statt unter name.github.io/repo-name/_astro/.... Dort liegt nichts, also kommt eine 404.

site und base in der astro.config setzen

Die Lösung steht in zwei Zeilen der astro.config.mjs. site ist die Adresse von GitHub Pages, base ist der Name des Repositorys mit Schrägstrich davor:

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://name.github.io',
  base: '/repo-name',
})

Damit baut Astro alle eigenen Assets mit dem richtigen Pfad. CSS und JavaScript aus dem Build funktionieren sofort wieder. Eure eigenen Links und Bilder müsst ihr noch anpassen.

Interne Links mit BASE_URL bauen

Mit gesetztem base brauchen alle internen Links diesen Pfad als Präfix. Ein Link auf /about landet sonst wieder im Hauptverzeichnis. Den Wert lest ihr über import.meta.env.BASE_URL aus. Ob er mit Schrägstrich endet, hängt von der Einstellung trailingSlash ab. Ein kleiner Trick macht euch davon unabhängig:

---
const base = import.meta.env.BASE_URL.replace(/\/$/, '');
---
<a href={`${base}/about/`}>Über uns</a>
<img src={`${base}/logo.svg`} alt="Logo von Never Code Alone" />

Die Zeile entfernt einen möglichen Schrägstrich am Ende. Danach hängt ihr jeden Pfad mit Schrägstrich an. Bei vielen Links lohnt sich eine kleine Hilfsfunktion in einer eigenen Datei, die ihr überall importiert.

Bilder und Dateien aus dem public Ordner

Dateien in public/ kopiert Astro unverändert in den Build. Astro passt die Pfade darauf nicht an, wenn ihr sie als festen Text schreibt. Laut Astro Doku brauchen alle statischen Asset Pfade den base Pfad als Präfix. Das betrifft Logos, Favicons, PDFs und Open Graph Bilder. Bilder, die ihr über astro:assets importiert, baut Astro dagegen selbst mit dem richtigen Pfad.

Wann ihr kein base braucht

• User oder Organisation Seite: Heißt das Repository name.github.io, liegt die Seite im Hauptverzeichnis. Dann reicht site.
• Eigene Domain: Mit eigener Domain liegt die Seite ebenfalls im Hauptverzeichnis. Dann entfernt ihr base komplett.

Umzug auf eine eigene Domain

Viele starten mit der GitHub Adresse und ziehen später auf eine eigene Domain um. Dann dreht sich alles wieder um. So geht ihr vor:

1. DNS beim Anbieter eurer Domain nach der GitHub Doku einrichten.
2. Eine Datei public/CNAME mit eurer Domain als einzige Zeile anlegen, etwa www.eure-domain.de.
3. In der astro.config.mjs die Domain bei site eintragen und base löschen.
4. Alle festen Präfixe mit dem Repository Namen aus den Links entfernen.
5. In den Settings unter Pages die Domain prüfen lassen und HTTPS erzwingen.

Wer seine Links von Anfang an über BASE_URL baut, muss beim Umzug in Schritt 4 nichts tun. Das ist der beste Grund für den Trick oben. Die Details zur Domain stehen in der GitHub Doku zu eigenen Domains.

Wenn die Seite gar nicht erscheint

Seht ihr überhaupt nichts oder nur eine alte Version, liegt das Problem meist im Deploy. Prüft diese Punkte:

• In den Settings unter Pages steht als Source GitHub Actions.
• Die Workflow Datei liegt unter .github/workflows/ und nutzt die offizielle Astro Action.
• Das Lockfile ist committet, also package-lock.json, pnpm-lock.yaml oder ein anderes.
• Im Actions Tab ist der letzte Lauf grün. Ein roter Build veröffentlicht nichts.
• Der Branch im Workflow passt zu eurem Hauptbranch, zum Beispiel main.

Den passenden Workflow beschreibt die Astro Anleitung für GitHub Pages. Die Bedeutung von base im Detail erklärt die Astro Konfigurationsreferenz.

Eine eigene 404 Seite anlegen

Legt eine Datei src/pages/404.astro an. Astro baut daraus eine 404.html, und GitHub Pages zeigt sie bei unbekannten Adressen statt der Standardseite. Achtet auch dort auf Links mit base. Sonst führt der Link zurück zur Startseite selbst ins Leere. Mehr dazu steht in der GitHub Doku zu eigenen 404 Seiten.

So verhindert ihr den Fehler dauerhaft

Der Fehler kommt gern zurück. Gerade Coding Agents schreiben Links wie /about, weil das in den meisten Projekten richtig ist. Drei Dinge helfen:

• Eine Regel für den Agent: In der AGENTS.md steht, dass interne Links immer über BASE_URL gebaut werden. Einen passenden Check als Slash Befehl zeigt OpenCode Commands erstellen.
• Ein Linktest nach dem Build: Cypress öffnet die gebaute Seite und prüft Navigation, Bilder und Links. Für Basistests mit einer Zeile im CI gibt es unser Cypress Base Plugin.
• Preview vor dem Push: Mit npm run build und npm run preview seht ihr die gebaute Seite lokal mit base Pfad.

Checkliste für Astro auf GitHub Pages

Punkt	Ohne eigene Domain	Mit eigener Domain
site	https://name.github.io	https://eure-domain.de
base	/repo-name	nicht setzen
Interne Links	mit BASE_URL	mit BASE_URL schadet nicht
public/CNAME	nicht nötig	eine Zeile mit der Domain
Source in Pages	GitHub Actions	GitHub Actions
HTTPS	automatisch	in den Settings erzwingen

Wie wir Teams mit Astro und Vibe Coding helfen

Astro nutzen wir täglich für Landingpages, Tools und Frontends. Viele davon laufen auf GitHub Pages, gebaut mit OpenCode und Open Weight Modellen. Alle Tipps für diesen Weg stehen in unseren Vibe Coding Tipps und Tricks für Astro. Wie eine echte Marke so entsteht, zeigt der Beitrag zur Landingpage mit Astro und Vibe Coding. Was sich beim Build seit Astro 7 geändert hat, steht in Warum dein Astro Build nach dem Upgrade anders aussieht.

Frontends mit Astro bauen wir im Frontend Development. Den Weg vom Prototyp zur Live Seite begleiten wir in der Vibe Coding Beratung. Wer gerade erst startet, liest Vibe Coding anfangen. Und warum jede Seite Tests braucht, steht in End to End Tests für jedes Webprojekt. Das Vorgespräch ist kostenlos, abgerechnet wird transparent nach Minuten.

Häufige Fragen zu Astro und GitHub Pages

Warum zeigt Astro auf GitHub Pages 2026 eine 404?

Meist fehlt der base Pfad. Ohne eigene Domain liegt die Seite unter name.github.io/repo-name. Astro baut die Pfade aber für das Hauptverzeichnis. Dann sucht der Browser CSS, Bilder und Unterseiten an der falschen Stelle. Setzt site und base in der astro.config, dann passen die Pfade wieder.

Warum fehlt das CSS auf GitHub Pages 2026?

Das CSS liegt im Build unter _astro im Unterordner eures Repositorys. Ohne base sucht der Browser es im Hauptverzeichnis der GitHub Adresse und findet nichts. Sobald base auf den Namen des Repositorys gesetzt ist, baut Astro die richtigen Pfade, und das CSS lädt wieder.

Was trage ich 2026 bei base in Astro ein?

Den Namen des Repositorys mit Schrägstrich davor, zum Beispiel /repo-name. Heißt das Repository name.github.io oder nutzt ihr eine eigene Domain, lasst ihr base weg. In site steht immer die volle Adresse, unter der die Seite erreichbar ist.

Wie baue ich Links mit base in Astro 2026?

Lest den Pfad über import.meta.env.BASE_URL aus und entfernt einen möglichen Schrägstrich am Ende. Danach setzt ihr ihn vor jeden internen Link und jede Datei aus public. So funktionieren die Links mit und ohne base, und ein späterer Umzug auf eine eigene Domain bleibt einfach.

Brauche ich mit eigener Domain noch base?

Nein. Mit eigener Domain liegt die Seite im Hauptverzeichnis. Legt eine Datei public/CNAME mit der Domain an, setzt site auf die Domain und entfernt base. Feste Präfixe mit dem Repository Namen müssen dann aus den Links raus. Links über BASE_URL passen sich selbst an.

Warum erscheint meine Astro Seite gar nicht auf GitHub Pages?

Prüft zuerst die Source in den Settings unter Pages. Sie muss auf GitHub Actions stehen. Dann prüft ihr, ob der letzte Lauf im Actions Tab grün ist, ob das Lockfile committet ist und ob der Branch im Workflow stimmt. Ein fehlgeschlagener Build veröffentlicht nichts.