Puppeteer-Vollbildschirmfotos: So vermeiden Sie verschwundene feste Kopfzeilen

Die Fehlersuche in Webautomatisierungstools kann stundenlang dauern – besonders, wenn Elemente wie feste Kopfzeilen plötzlich verschwinden. Genau das passiert mit Puppeteer, wenn Sie page.screenshot({ fullPage: true }) ausführen. Während die Seite im normalen Browser einwandfrei aussieht, zeigt das generierte Bild oder PDF den Header nicht mehr dort, wo er hingehört. Doch warum verschwindet er überhaupt?

Warum feste Kopfzeilen in Puppeteer-Vollbildschirmaufnahmen falsch platziert werden

Puppeteer nutzt für fullPage: true den Chrome DevTools Protocol-Befehl captureBeyondViewport. Dieser rasterisiert das gesamte Dokument außerhalb der aktuellen Ansichtsfensterbreite. Allerdings werden Elemente mit position: fixed relativ zum sichtbaren Bereich des Browsers positioniert, nicht zum gesamten Dokument. Wenn Ihr Skript die Seite vor dem Screenshot nach unten scrollt, wird der Header infolgedessen am unteren Rand des Bildes platziert – statt oben.

Ein zweiter häufiger Grund ist die CSS-Property scroll-behavior: smooth. Viele Websites nutzen diesen Stil, um Scrollvorgänge sanft zu animieren. Wenn Sie window.scrollTo(0, 0) ausführen, dauert die Animation jedoch länger als die Puppeteer-Screenshot-Erstellung. In diesem Fall wird der Header in einer Zwischenposition eingefroren, was zu leeren Bereichen oder falscher Anzeige führt.

Drei Lösungen für korrekte Kopfzeilen in Screenshots

Damit der Header in Puppeteer-Vollbildschirmaufnahmen korrekt angezeigt wird, müssen drei Punkte beachtet werden:

• Deaktivieren Sie sanfte Scrollanimationen – Der Befehl scrollTo muss sofort ausgeführt werden.
• Setzen Sie alle durch Scroll-Events versteckten Stile zurück – Viele Websites verstecken Kopfzeilen bei Scrollen nach unten.
• Scrollen Sie explizit nach oben und warten Sie auf die Bildschirmaktualisierung – Nur so wird sichergestellt, dass der Header neu gerendert wird.

Hier ist ein praktisches JavaScript-Snippet, das diese Schritte automatisiert:

async function prepareForScreenshot(page) {
  await page.evaluate(() => {
    // Sanfte Scrollanimationen deaktivieren – sofortige Scrollausführung
    const style = document.createElement('style');
    style.textContent = 'html { scroll-behavior: auto !important; }';
    document.head.appendChild(style);

    // Versteckte Kopfzeilen-Elemente zurücksetzen
    const headers = document.querySelectorAll(
      'header, .header, [class*="header" i], nav[class*="header" i]'
    );
    headers.forEach(el => {
      const cs = window.getComputedStyle(el);
      if (['fixed', 'sticky'].includes(cs.position)) {
        el.style.setProperty('transform', 'none', 'important');
        el.style.setProperty('opacity', '1', 'important');
        el.style.setProperty('visibility', 'visible', 'important');
        if (cs.display === 'none') {
          el.style.setProperty('display', 'flex', 'important');
        }
        // Häufig genutzte Klassen für "bei Scrollen verstecken" entfernen
        ['hidden', 'is-hidden', 'scroll-up', 'scroll-down', 'header--hidden']
          .forEach(c => el.classList.remove(c));
      }
    });

    // Sofortiges Scrollen nach oben
    window.scrollTo(0, 0);
  });

  // Warten auf die Bildschirmaktualisierung (300 ms Puffer)
  await new Promise(r => setTimeout(r, 300));
}

Nutzen Sie diese Funktion direkt vor dem Screenshot:

await prepareForScreenshot(page);
await page.screenshot({ 
  path: 'screenshot.png', 
  fullPage: true 
});

Wann der einfache Fix nicht ausreicht – und wie Sie reagieren

Der beschriebene Ansatz funktioniert bei den meisten Websites problemlos. Allerdings gibt es zwei Ausnahmen, bei denen zusätzliche Maßnahmen erforderlich sind:

1. Transparente Kopfzeilen über Heldern

Wenn der Header über einem Hero-Bereich schwebt, wird er korrekt über dem Hintergrund platziert. Der einfache Fix reicht hier aus.

1. Dynamische Scroll-Event-Listener

Manche Websites nutzen JavaScript-Bibliotheken, die nach dem Zurücksetzen der Stile erneut Scroll-Events abfangen. In diesem Fall müssen Sie ein künstliches Scroll-Event auslösen, um die Logik zur Kopfzeigen-Anzeige neu zu starten:

window.scrollTo(0, 0);
window.dispatchEvent(new Event('scroll'));

Ein praktisches Tool für Website-Konvertierungen

Die beschriebene Lösung stammt aus meiner Arbeit an Site2PDF, einem Dienst, der Websites in PDF-, PNG-, JPG- oder ZIP-Dateien umwandelt. Der kostenlose Tarif umfasst fünf Konvertierungen pro Monat mit allen Formaten und erweiterten Optionen wie Cookie-Banner-Entfernung oder automatischer Kopfzeigen-Korrektur.

Falls Sie ähnliche Probleme in Ihrer Automatisierung erleben, können Sie dieses Snippet als Ausgangspunkt nutzen. Die Kombination aus CSS-Reset, JavaScript-Steuerung und Pufferzeit löst das Problem zuverlässig – und spart Ihnen stundenlange Debugging-Sessions.