Die Bereitstellung einer Vite/React-Anwendung auf GitHub Pages ist ein aufregender Meilenstein, aber der Prozess kann manchmal mit unerwarteten Herausforderungen verbunden sein, insbesondere beim Umgang mit Bildern und Assets. Dieser Blogbeitrag führt Sie durch den gesamten Prozess, von der ersten Bereitstellung über die Fehlerbehebung bei häufigen Problemen bis hin zur Erzielung effektiver Lösungen.

Egal, ob Sie Anfänger oder jemand mit Erfahrung sind, dieser Leitfaden hilft Ihnen, häufige Fallstricke zu vermeiden und Ihre Vite/React-App erfolgreich bereitzustellen, wobei alle Assets ordnungsgemäß gerendert werden.

Voraussetzungen

Bevor wir eintauchen, stellen Sie sicher, dass Sie Folgendes haben:

• Ein Vite/React-Projekt: In diesem Handbuch wird davon ausgegangen, dass Sie Ihr Projekt mit Vite als Build-Tool und React als Framework eingerichtet haben.
• GitHub-Repository: Sie sollten über ein vorhandenes GitHub-Repository verfügen, in das Sie Ihre Anwendung zur Bereitstellung übertragen.
• GitHub Pages aktiviert: Stellen Sie sicher, dass GitHub Pages in den Einstellungen Ihres Repositorys für die Bereitstellung aktiviert ist.

Schritt 1: Initialisieren Sie die Bereitstellung des Projekts und der GitHub-Seiten

Stellen Sie zunächst sicher, dass Ihre Vite/React-Anwendung ordnungsgemäß initialisiert ist und auf localhost funktioniert. Sie können ein einfaches Vite-Projekt wie folgt erstellen:

npm create vite@latest

Abhängigkeiten installieren:

npm install

Führen Sie das Projekt lokal aus, um zu bestätigen, dass alles funktioniert:

npm run dev

Sobald Ihr Projekt fertig ist, übertragen Sie es in Ihr GitHub-Repository.

Erstellen Sie eine vite.config.js für GitHub-Seiten

GitHub Pages erwartet, dass die Anwendung von einer bestimmten Basis-URL bereitgestellt wird, bei der es sich normalerweise um Ihren Repository-Namen handelt. Aktualisieren Sie die Datei vite.config.js, um Folgendes widerzuspiegeln:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

Die Basisoption stellt sicher, dass die Anwendung bei der Bereitstellung den richtigen Basispfad verwendet.

Schritt 2: Erstellen und Bereitstellen des Projekts

Sie müssen das gh-pages-Paket installieren, um die Bereitstellung durchzuführen.

npm install gh-pages --save-dev

Fügen Sie in Ihrer package.json die folgenden Skripte hinzu, um den Bereitstellungsprozess zu automatisieren:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

Führen Sie die Bereitstellung aus:

npm run deploy

Zu diesem Zeitpunkt sollte Ihr Projekt unter https://.github.io// live sein, aber wenn Sie wie ich sind, könnten einige Probleme auftreten wenn die App nicht richtig gerendert wird oder Bilder nicht angezeigt werden.

Schritt 3: Häufige Probleme und Lösungen

Problem 1: Leere Seite nach der Bereitstellung

Nach der Bereitstellung stellen Sie möglicherweise fest, dass die App eine leere Seite lädt. Dies wird häufig durch Routing-Probleme verursacht. Standardmäßig wird BrowserRouter von „react-router-dom“ verwendet, der auf serverseitigem Routing basiert, aber GitHub Pages stellt statische Dateien bereit und verarbeitet keine clientseitigen Routen.

Lösung: HashRouter verwenden

Um dieses Problem zu lösen, wechseln Sie in Ihrer index.js- oder main.jsx-Datei von BrowserRouter zu HashRouter.

Hinweis: Es ist nicht erforderlich, dass Sie über eine praktische UI-Bibliothek verfügen, die ich in meinen Projekten sehr häufig verwende.

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
);

HashRouter verwendet ein Hash-Symbol (#) in der URL, um den Navigationsstatus zu verfolgen, sodass GitHub Pages verschiedene Routen ordnungsgemäß bereitstellen kann, ohne einen 404-Fehler zurückzugeben.

Problem 2: 404-Fehler bei der Aktualisierung oder anderen Routen

Nachdem Sie das Problem mit der leeren Seite behoben haben, besteht möglicherweise ein weiteres Problem darin, dass die App auf der Startseite funktioniert, beim Navigieren zu anderen Routen jedoch einen 404-Fehler anzeigt, insbesondere wenn Sie direkt auf eine Route wie /blogs oder /projects zugreifen.

Dies geschieht, weil GitHub Pages nur weiß, wie die Datei index.html bereitgestellt werden soll, und keine von React Router verwalteten Routen erkennt.

Lösung: Behandeln Sie 404-Fehler in den GitHub-Seiteneinstellungen

Um dies zu beheben, müssen Sie eine 404.html-Datei in Ihrem öffentlichen/-Ordner erstellen. Diese Datei stellt sicher, dass GitHub Pages Ihre index.html-Datei für alle Routen bereitstellt, die es nicht erkennt, sodass React Router das Routing übernehmen kann:

1. Kopieren Sie Ihre index.html in eine neue Datei mit dem Namen 404.html.
2. Legen Sie diese Datei in Ihren öffentlichen/-Ordner.
3. Erstellen Sie das Projekt neu und stellen Sie es erneut bereit.

Problem 3: Bilder werden in der Produktion nicht geladen

Eines der häufigsten Bereitstellungsprobleme ist, dass Bilder nicht richtig geladen werden. Während sie auf localhost einwandfrei funktionieren, werden Ihnen nach der Bereitstellung auf GitHub-Seiten möglicherweise fehlerhafte Bildlinks auffallen.

Sie könnten beispielsweise in Ihren Komponenten auf ein Bild wie dieses verweisen:

Problem: Falsche Bildpfade

Das Problem hierbei ist, dass absolute Pfade (beginnend mit /) nicht gut funktionieren, wenn die App in einem Unterverzeichnis bereitgestellt wird (z. B. /Ihr-Repo-Name/). GitHub Pages versucht, das Bild unter https://.github.io/Images/myImage.png statt unter https://.github.io/your-repo-name/Images/myImage.png zu finden , was zu einem 404-Fehler führt.

Lösung: BASE_URL verwenden

Um dies zu beheben, verschieben Sie alle Ihre Bilder in „Öffentlich/Bilder“. Dies ist zwar optional, ich würde Ihnen jedoch dringend empfehlen, dies zu tun. Anschließend stellen Sie die BASE_URL basierend auf der Umgebung dynamisch den Bildpfaden voran:

1. Definieren Sie eine BASE_URL-Konstante, die von der Umgebung abhängt:

   const BASE_URL = import.meta.env.BASE_URL;

1. Verwenden Sie diese BASE_URL, wenn Sie auf Bilder verweisen:

HINWEIS: Vergessen Sie nicht, das „/“ vor „Bilder“ zu entfernen, sonst wird es verdoppelt, eines von der BASE_URL und ein weiteres von den „/Images“, die Sie vergessen haben zu entfernen.

Dadurch wird sichergestellt, dass sowohl in der Entwicklung (localhost) als auch in der Produktion (GitHub Pages) der richtige Pfad verwendet wird.

Schritt 4: Endgültige Bereitstellung

Nachdem Sie die Korrekturen für Routing und Bildpfade implementiert haben, erstellen Sie Ihre Anwendung neu und stellen Sie sie erneut bereit:

npm run build
npm run deploy

Ihre Vite/React-Anwendung sollte jetzt vollständig bereitgestellt sein, alle Bilder korrekt gerendert und alle Routen ordnungsgemäß verarbeitet.

Zusammenfassung:

1. Routing-Probleme: Verwenden Sie HashRouter für ordnungsgemäßes Routing in statischen Bereitstellungen wie GitHub Pages.
2. 404-Fehler auf Routen: Erstellen Sie eine 404.html-Datei, um sicherzustellen, dass GitHub Pages Ihre App korrekt bereitstellt.
3. Bilder werden nicht geladen: Verschieben Sie alle Bilder nach Public/Images und hängen Sie BASE_URL dynamisch an Ihre Asset-Pfade an, um sowohl Entwicklungs- als auch Produktionsumgebungen zu verwalten.

Mit diesen Schritten sollte Ihre Vite/React-App live sein und reibungslos auf GitHub-Seiten funktionieren. Viel Spaß beim Codieren und Bereitstellen!