Eine Hugo-Website auf Vercel bereitstellen: Wichtige Fallstricke

Eine Hugo-Website mit dem Blowfish-Theme auf Vercel bereitzustellen ist großartig, aber es können einige häufige Probleme auftreten. Hier ist ein sehr knapper Leitfaden zu den Problemen, auf die ich gestoßen bin, und deren Lösungen.

1. Vercel zeigt XML an oder meldet “Konfigurationsdatei kann nicht gefunden werden”

#

Symptom: Ihr Vercel-Deployment zeigt entweder einen XML-Feed anstelle Ihrer Website an, oder der Build schlägt mit einem Fehler wie “Unable to locate config file” (Konfigurationsdatei kann nicht gefunden werden) fehl.

Ursache: Sie haben wahrscheinlich nur Ihren Hugo public/-Ordner (das Build-Ergebnis) nach GitHub gepusht, oder die Einstellung Root Directory (Stammverzeichnis) in Vercel ist falsch, falls sich Ihr Hugo-Quellcode in einem Unterordner Ihres Repositories befindet.

Lösung:

• Vollständigen Hugo-Quellcode pushen: Vercel benötigt Ihren gesamten Hugo-Projektquellcode, nicht nur den public/-Ordner. Vercel wird die Seite selbst erstellen.
• Vercel-Stammverzeichnis festlegen: Wenn sich Ihre Hugo-Website nicht im Stammverzeichnis des Git-Repositories befindet, setzen Sie das Root Directory in Vercel so, dass es auf den Unterordner Ihres Hugo-Projekts verweist.

2. Falsche Hugo-Version & Theme-Fehler

#

Symptom: Build-Fehler wie function "X" not defined, oder Theme-Funktionen (wie die Bildverarbeitung von Blowfish) schlagen fehl. Die Vercel-Logs zeigen möglicherweise eine alte Hugo-Version an.

Ursache: Vercel hat standardmäßig eine ältere Hugo-Version (0.58.0, als ich es versuchte, eine extrem alte Version) verwendet, die nicht mit den Anforderungen Ihres Themes kompatibel ist.

Lösung:

• Setzen Sie in den Vercel-Projekteinstellungen > Umgebungsvariablen HUGO_VERSION auf Ihre erforderliche Version (z. B. 0.128.0). Stellen Sie sicher, dass es sich um eine extended-Version handelt, die für SASS/SCSS-Themes wie Blowfish erforderlich ist.

3. Anzeigeprobleme mit dem Avatar im Blowfish-Theme

#

Symptom: Der Autoren-Avatar wird nicht angezeigt, oder es treten Build-Fehler wie resources.GetRemote ... unsupported protocol scheme "" im Zusammenhang mit author.html auf.

Ursache: Die Logik des Themes in partials/author.html könnte beim Versuch, ein lokales Autoren-Bild (aus assets/) zu verarbeiten, in einen fehlerhaften Fehlerbehandlungszweig geraten, der resources.GetRemote falsch verwendet.

Lösung (Wichtiger Tipp unten):

• Der problematische else-Block in der author.html des Themes (der fälschlicherweise resources.GetRemote . versuchte) muss so geändert werden, dass er Fälle, in denen der primäre Bildabruf (resources.Get "path/to/avatar.png") fehlschlägt, elegant behandelt – vielleicht durch das Protokollieren einer Warnung und die Anzeige keines Bildes, anstatt den Build zum Absturz zu bringen. Ersetzen Sie den Code in layouts/partials/author.html durch den folgenden:

{{ $disableImageOptimization := .Site.Params.disableImageOptimization | default false }}
<div class="flex author">
  {{ with .Site.Params.Author.image }} {{/* Nur fortfahren, wenn ein Bildpfad konfiguriert ist */}}
    {{ $authorImagePath := . }} {{/* Den konfigurierten Pfad speichern */}}
    {{ $authorImage := "" }}

    {{/* Versuchen, die Bildressource abzurufen */}}
    {{ if or (strings.HasPrefix $authorImagePath "http:") (strings.HasPrefix $authorImagePath "https:") }}
      {{ $authorImage = resources.GetRemote $authorImagePath }}
    {{ else }}
      {{ $authorImage = resources.Get $authorImagePath }}
    {{ end }}

    {{/* Nur verarbeiten und anzeigen, wenn $authorImage eine gültige Ressource ist */}}
    {{ if $authorImage }}
      {{ if not $disableImageOptimization }}
        {{ $authorImage = $authorImage.Fill "192x192" }}
      {{ end }}
      <img class="!mt-0 !mb-0 h-24 w-24 rounded-full ltr:mr-4 rtl:ml-4" width="96" height="96"
      alt="{{ $.Site.Params.Author.name | default " Author" }}" src="{{ $authorImage.RelPermalink }}" />
    {{ else }}
      {{/*
        OPTIONAL: Eine Warnung protokollieren, wenn das Bild nicht geladen werden konnte.
        Dies erscheint in Ihrer 'hugo server'-Konsole oder den Vercel-Build-Logs.
      */}}
      {{ warnf "Author image configured at '%s' could not be loaded or processed." $authorImagePath }}
      {{/* Hier nichts tun oder einen Platzhalter anzeigen, wenn Sie es bevorzugen */}}
      {{/* Beispiel-Platzhalter (optional): <div class="!mt-0 !mb-0 h-24 w-24 rounded-full ltr:mr-4 rtl:ml-4 bg-gray-200"></div> */}}
    {{ end }}
  {{ end }} {{/* Ende von 'with .Site.Params.Author.image' */}}

  <div class="place-self-center">
    {{ with .Site.Params.Author.name | markdownify }}
    <div class="text-[0.6rem] uppercase leading-3 text-neutral-500 dark:text-neutral-400">
      {{ i18n "author.byline_title" | markdownify }}
    </div>
    <div class="font-semibold leading-6 text-neutral-800 dark:text-neutral-300">
      {{ . }}
    </div>
    {{ end }}
    {{ with .Site.Params.Author.bio | markdownify }}
    <div class="text-sm text-neutral-700 dark:text-neutral-400">{{ . }}</div>
    {{ end }}
    <div class="text-2xl sm:text-lg">{{ partialCached "author-links.html" . }}</div>
  </div>
</div>

4. Website wird ohne CSS oder mit falschen Theme-Farben bereitgestellt

#

Symptom: Der HTML-Inhalt wird geladen, aber das gesamte CSS-Styling fehlt, oder ein konfiguriertes colorScheme (z. B. “fire”) wird auf Vercel nicht angewendet (selbst wenn es lokal funktioniert).

Lösungen:

• baseURL in hugo.toml/config.toml: Entscheidend! Stellen Sie sicher, dass baseURL auf Ihre endgültige Vercel-URL (z. B. https://your-name.vercel.app/ oder eine benutzerdefinierte Domain) verweist, bevor Sie die Seite bereitstellen. Dies ist eine häufige Ursache für defekte Asset-Pfade.
• Groß-/Kleinschreibung (für colorScheme): Vercel (Linux) ist case-sensitiv (achtet auf Groß- und Kleinschreibung). Wenn Ihre Theme-Datei fire.css heißt, Ihre Konfiguration aber colorScheme = "Fire" lautet, schlägt dies fehl.
  • Lösung: Verwenden Sie Kleinbuchstaben für colorScheme in params.toml, damit es mit dem CSS-Dateinamen übereinstimmt (z. B. colorScheme = "fire").

Profi-Tipp: Theme-Dateien korrekt ändern

#

Bearbeiten Sie Dateien nicht direkt im themes/blowfish/-Ordner, wenn es sich um ein Git-Submodul handelt. Ihre Git-Commits im Hauptprojekt werden diese Änderungen nicht direkt verfolgen, und Theme-Updates werden sie überschreiben.

Stattdessen überschreiben Sie Theme-Dateien:

1. Kopieren Sie die spezifischen Dateien aus dem themes-Ordner (z. B. archetypes, assets, images, layouts, static) in den exakt gleichen Pfad in den Stammordnern Ihres Projekts.
2. Ändern Sie diese kopierten Dateien. Hugo priorisiert Dateien im Stammverzeichnis Ihres Projekts gegenüber den Theme-Dateien.

Vorteile:

• Ihre Anpassungen sind Teil der Git-Historie Ihres Hauptprojekts.
• Theme-Updates werden Ihre Änderungen nicht überschreiben (obwohl Sie möglicherweise später Theme-Updates manuell in Ihre überschriebenen Dateien einpflegen müssen).
• Hält Ihr Theme für einfachere Updates “sauber”.