Bereitstellen einer Astro-Site auf GitHub Pages mit GitHub-Aktionen

Astro ist ein modernes Frontend-Framework für die Erstellung schneller, optimierter Websites. Es erlaubt Ihnen, Komponenten mit Ihrem bevorzugten JavaScript-Framework (wie React, Vue oder Svelte) zu schreiben, rendert sie aber zur Erstellungszeit als statisches HTML, um das Laden der Seite zu beschleunigen. Darüber hinaus bietet Astro serverseitige Rendering-Funktionen und lässt sich gut mit gängigen Tools und Frameworks integrieren, was die Leistung und die Suchmaschinenoptimierung verbessert.

Dieser Blog wird mit Astro erstellt und mit GitHub Actions auf GitHub Pages bereitgestellt. Wie in meinem [ersten Beitrag] versprochen, beschreibe ich, wie diese Website bereitgestellt wird und welche Konfigurationen vorgenommen werden müssen, um erfolgreich zu sein, selbst wenn Sie eine benutzerdefinierte Domain im Sinn haben. Astro selbst bietet eine detaillierte Anleitung, die Sie ebenfalls verwenden sollten.

Projekt vorbereiten

Für die folgenden Schritte benötigen Sie eine funktionierende Astro-Website in einem Repository auf GitHub. Falls Sie ein Projekt benötigen, mit dem Sie beginnen können, können Sie

npm create astro@latest -- --template satnaing/astro-paper

um den Basiscode dieses Blogs unter Verwendung des [Astro Paper-Themas] zu erstellen.

Wählen Sie den Namen des Repositorys als {your-handle}.github.io, da GitHub dies als Ihre persönliche Seite erkennt und die entsprechende Domain kostenlos zur Verfügung stellt. Sie können jedoch auch einen anderen Namen wählen, wenn Sie eine benutzerdefinierte Domain verwenden, ohne die von GitHub zur Verfügung gestellte URL zu benötigen, oder mit der Standard-URL zufrieden sind, unter der Ihre Seite unter https://{your-handle}.github.io/{name-of-repository} verfügbar ist.

In diesem Tutorial wird der Einfachheit halber {your-handle}.github.io als Repository-Name verwendet.

Bitte beachten Sie, dass das Repository öffentlich sein muss, wenn Sie den kostenlosen GitHub-Plan verwenden. Das Repository kann privat sein, wenn Sie einen kostenpflichtigen GitHub-Plan haben, z. B. GitHub Pro für die persönliche Nutzung von GitHub Teams, wenn sich das Repository in einer Organisation befindet.

GitHub Seiten aktivieren

GitHub Pages muss für das Repository aktiviert sein.

1. Gehen Sie zu Einstellungen > Seiten des Repositorys (1)
2. Wählen Sie GitHub-Aktionen als Quelle (2) und (3)

Standardmäßig sollte im Repository einer Astro-Seite kein Workflow verfügbar sein, so dass nach der Auswahl von GitHub Actions als Quelle nichts passiert.

Workflow hinzufügen, der die Seite einsetzt

Jetzt, wo GitHub Actions als Quelle für GitHub Pages ausgewählt ist, muss dem Repository ein Workflow hinzugefügt werden. Erstellen Sie eine neue Workflow-Datei, z.B. .github/workflows/deploy-website.yml, und fügen Sie den folgenden Code in die neue Datei ein und übertragen Sie die Änderungen in den Standardzweig. Beachten Sie, dass der Workflow in der Standardverzweigung, in meinem Fall main, liegen muss, damit er ordnungsgemäß funktioniert - andernfalls wird nichts bereitgestellt.

name: Deploy Website to GitHub Pages

on:
  push:
    branches: [main]
    paths-ignore:
      - README.md
  workflow_dispatch:

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          show-progress: false
      - name: Install, build, and upload site
        uses: withastro/action@v1

  deploy:
    name: Deploy
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Der Workflow verwendet die withastro/action Eine von Astro bereitgestellte Aktion, die das Projekt erstellt, damit es auf GitHub Pages bereitgestellt werden kann. Sobald die Seite im ersten Job erfolgreich erstellt wurde, wird die GitHub actions/deploy-pages Aktion stellt die Website auf GitHub Pages bereit. Bitte beachten Sie, dass die angegebene permissions sowie die environment Informationen für die Bereitstellung auf GitHub Pages erforderlich sind.

Um zu sehen, ob es funktioniert, gehen Sie auf die Registerkarte Aktionen des Repositorys und überprüfen Sie, ob der Workflow läuft. Sobald der Workflow erfolgreich war, ist die Seite unter https://{your-handle}.github.io oder der von GitHub angegebenen Domain verfügbar, wenn Sie nicht den spezifischen Repository-Namen verwenden. Am einfachsten ist es, wenn Sie in der GitHub-Benutzeroberfläche zum Stammverzeichnis Ihres Repositorys gehen und nach der URL im Abschnitt Über suchen, wie im Screenshot unten gezeigt.

Benutzerdefinierte Domäne verwenden

GitHub Pages ist in der Lage, die Website unter einer von Ihnen angegebenen Domain bereitzustellen. Die Dokumentation ist detailliert und die nachfolgenden Schritte sollen alle notwendigen Schritte in knapper Form vermitteln. Sie benötigen eine Domain Ihrer Wahl und Zugang zu den DNS-Einstellungen dieser Domain.

Seien Sie nicht verwirrt, denn wir werden in einigen der folgenden Schritte {your-handle}.github.io als Ziel für Ihre benutzerdefinierte Domain festlegen. Dies ist erforderlich, da die Domain {your-handle}.github.io neben der benutzerdefinierten Domain existiert und die Website weiterhin unter dieser Domain erreichbar ist.

DNS vorbereiten

Die DNS-Einstellungen für Ihre Domain müssen vorbereitet werden. Je nachdem, ob Sie eine Subdomain verwenden möchten, wie z.B. und , oder ob Sie eine Apex-Domain, d.h. keine Subdomain, verwenden möchten, sind in den DNS-Einstellungen entsprechende Einträge erforderlich, die ich gerne aufdröseln möchte, da die Dokumentation für mich anfangs nicht klar war. Um loszulegen, öffnen Sie die DNS-Einstellungen Ihrer Domain und fügen Sie je nach gewünschter Einrichtung die folgenden Einträge hinzu.

Bitte beachten Sie, dass es mehrere Stunden dauern kann, bis DNS-Aktualisierungen wirksam werden.

Verwenden Sie nur die Subdomain oder in Kombination mit der Apex-Domain (CNAME)

Wenn Sie nur eine Subdomain verwenden möchten, fügen Sie einen CNAME Datensatztyp für die gewünschte Subdomain hinzu, der auf Ihre GitHub-Seite zeigt und den Wert

{your-handle}.github.io

Wenn Sie sowohl eine Apex- als auch eine Subdomain verwenden möchten, fügen Sie diesen Eintrag unten neben Ihrer Apex-Domain hinzu. Wenn nicht, haben Sie alles vorbereitet und können mit Domainkonfiguration zum Projekt hinzufügen fortfahren.

Apex-Domäne verwenden

Um eine Apex-Domäne verwenden zu können, stehen Ihnen einige Optionen zur Verfügung, z. B.

• ANAME oder ALIAS aufnehmen,
• A Eintrag (IPv4),
• AAAA Eintrag (IPv6).

Bitte lesen Sie die folgenden Optionen sorgfältig durch und fügen Sie einige davon parallel hinzu, falls erforderlich oder empfohlen.

ANAME oder ALIAS aufnehmen.

Fügen Sie einen ANAME oder ALIAS Eintrag hinzu und legen Sie die Subdomain als @ fest. Geben Sie als Wert

{your-handle}.github.io

Das war's und Sie können mit dem Abschnitt Domainkonfiguration zum Projekt hinzufügen fortfahren. Wenn Ihre DNS-Einstellungen nicht ANAME oder ALIAS als Eintragstyp vorsehen, fügen Sie wie unten beschrieben einen A oder AAAA Eintrag hinzu.

A Eintrag (IPv4)

Anstelle von ALIAS oder ANAME können Sie A Einträge (IPv4) mit @ als Subdomain eingeben. Fügen Sie jede der IPs als separate Einträge hinzu.

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

AAAA Datensatz (IPv6)

Wenn Sie IPv6 unterstützen möchten, fügen Sie die folgenden IPs als AAAA Eintragstyp und @ als Subdomain hinzu. Bitte fügen Sie parallel dazu wie oben beschrieben einen A Eintrag hinzu, da IPv6 nur langsam angenommen wird.

2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

Der folgende Screenshot ist ein praktisches Beispiel für meine DNS-Einstellungen dieser Website mit allen oben genannten Einstellungen. Bitte beachten Sie, dass meine DNS-Einstellungen keine ANAME (oder alternativ ALIAS) vorsehen, so dass ich stattdessen die Einträge A und AAAA hinzugefügt habe.

Domänenkonfiguration zum Projekt hinzufügen

Die benutzerdefinierte Domain muss zur Site-Konfiguration Ihres Astro-Projekts hinzugefügt werden. Öffnen Sie die Datei astro.config.ts im Stammverzeichnis des Projekts und fügen Sie Ihre Domain ({your-domain}) als site hinzu.

export default defineConfig({
  site: {your-domain},

Erstellen Sie außerdem eine Datei namens CNAME (ohne Dateierweiterung) im Ordner public und fügen Sie als Inhalt die Domain ({your-domain}) Ihrer Website hinzu:

{your-domain}

Benutzerdefinierte Domain zu Einstellungen hinzufügen

Nun, da alles eingerichtet und konfiguriert ist, muss die benutzerdefinierte Domain zu den GitHub Pages-Einstellungen des Repositorys hinzugefügt werden. Kehren Sie also zu Einstellungen > Seiten zurück und fügen Sie Ihre benutzerdefinierte Domain im Textfeld im Abschnitt Benutzerdefinierte Domain hinzu.

Überprüfen und sichern Sie Ihre benutzerdefinierte Domain

Es ist möglich, dass Ihre Domain übernommen oder missbraucht werden kann, während GitHub Pages deaktiviert ist. Um zu verhindern, dass andere GitHub-Nutzer Ihre Domain mit ihren Seiten-Konfigurationen verwenden, bietet GitHub eine Verifizierung für Ihre benutzerdefinierten Domains.

Öffnen Sie Ihre persönlichen Seiteneinstellungen über Avatar > Einstellungen > Seiten und fügen Sie Ihre Domain hinzu. GitHub stellt Ihnen TXT Datensatzeinstellungen zur Verfügung, die Sie in den DNS-Einstellungen Ihrer Domain hinzufügen müssen.

Sobald Ihre DNS-Einstellungen aktiv sind, können Sie auf Überprüfen klicken. Wenn die Überprüfung erfolgreich war, wird die Domain entsprechend aufgelistet und ist gesichert.

Das war's - Sie sind eingerichtet, Ihre Website ist live und die Domain gesichert.