Stage File Proxy: Nie wieder Dateien manuell kopieren – Die bessere Alternative.

Vor gut einem Jahr haben wir hier im Blog noch drupal/media_placeholder empfohlen. Tja – so schnell vergeht die Zeit. Das Modul wird nicht mehr aktiv entwickelt. Wer es noch im Einsatz hat, lebt auf geborgter Zeit. Hier kommt die deutlich bessere Alternative.

#Das Problem: Veraltete Platzhalter-Module und massive File-Syncs

Jeder Drupal-Entwickler kennt das Szenario: Du klonst ein Projekt, importierst die Datenbank, rufst die Seite auf – und starrst auf kaputte Bildplatzhalter. Überall. Die Medien-Dateien fehlen, weil du natürlich nicht den kompletten sites/default/files-Ordner mit seinen 8 GB mitgezogen hast.

Die klassischen Lösungsansätze waren bisher:

• Kompletter File-Sync: rsync oder scp vom Live-Server. Dauert ewig, frisst Speicher, muss regelmäßig wiederholt werden.
• Platzhalter-Module wie drupal/media_placeholder: Generieren Dummy-Bilder statt der echten Dateien. Funktioniert – bis das Modul nicht mehr gepflegt wird.
• Manuelle Kopien: „Kannst du mir mal den files-Ordner schicken?“ – Nein. Einfach nein.

Das Grundproblem bleibt: Du brauchst die Dateien vom Live-System in deiner lokalen Umgebung. Aber du willst weder Gigabytes synchronisieren noch auf Module setzen, die morgen vielleicht nicht mehr mit dem nächsten Drupal-Core-Update kompatibel sind.

drupal/media_placeholder hat seinen Job gemacht, keine Frage. Aber ein Modul ohne aktive Wartung in einem Projekt zu behalten, ist ein Risiko – besonders wenn es eine Lösung gibt, die nicht nur aktiv gepflegt wird, sondern das Problem grundlegend besser löst.

#Was ist Stage File Proxy?

Stage File Proxy ist ein Drupal-Modul, das einen radikal einfachen Ansatz verfolgt: Wenn deine lokale oder Staging-Umgebung eine Datei braucht, die nicht vorhanden ist, holt sie sich das Modul automatisch vom Live-System. On-the-fly. Transparent. Ohne dass du irgendetwas tun musst.

Konkret passiert Folgendes: Ein Besucher (oder du als Entwickler) ruft eine Seite auf, die ein Bild referenziert. Drupal stellt fest, dass die Datei lokal nicht existiert. Stage File Proxy fängt diesen Request ab, lädt die Datei vom konfigurierten Origin-Server herunter, speichert sie lokal – und liefert sie aus. Beim nächsten Aufruf ist die Datei schon da.

Das Modul existiert seit über einem Jahrzehnt, wird aktiv gepflegt und hat über 40.000 gemeldete Installationen. Es ist kein Experiment – es ist ein bewährtes Werkzeug, das in professionellen Drupal-Workflows längst zum Standard gehört.

#Warum Stage File Proxy besser ist als Platzhalter

Der Unterschied zwischen einem Platzhalter-Modul und Stage File Proxy ist fundamental:

• Echte Dateien statt Dummies: Du siehst exakt das, was auf Live zu sehen ist. Keine grauen Kästchen, keine generischen Platzhalter. Das ist besonders wichtig, wenn du an Layouts, Bildstilen oder responsiven Bildern arbeitest.
• Kein initialer Sync nötig: Du brauchst keinen files-Ordner beim Projekt-Setup. Null Bytes. Die Dateien kommen erst, wenn sie tatsächlich gebraucht werden.
• Speicherplatz on demand: Nur Dateien, die du wirklich aufrufst, werden heruntergeladen. Bei einem Projekt mit 50.000 Medien-Dateien landest du lokal vielleicht bei 200 – den Seiten, die du tatsächlich testest.
• Bildstile funktionieren: Stage File Proxy lädt die Originaldatei. Drupal generiert die Bildstile dann lokal wie gewohnt. Alles funktioniert exakt wie auf dem Live-System.
• Aktive Wartung: Das Modul wird kontinuierlich gepflegt und ist mit aktuellen Drupal-Versionen kompatibel.

#Setup in 3 Schritten: Composer, Drush, Config

Die Installation ist so simpel, dass es fast schon langweilig ist:

#Schritt 1: Modul installieren

composer require drupal/stage_file_proxy

#Schritt 2: Modul aktivieren

drush en stage_file_proxy

#Schritt 3: Origin konfigurieren

drush config:set stage_file_proxy.settings origin "https://www.meine-live-seite.de"

Das war’s. Ernsthaft. Ab sofort zieht sich deine lokale Umgebung fehlende Dateien automatisch vom Live-System.

#Optionale Konfiguration

Stage File Proxy bietet noch ein paar nützliche Einstellungen, die du über drush config:set oder die settings.php setzen kannst:

// In settings.php (empfohlen für lokale Umgebungen)
$config['stage_file_proxy.settings']['origin'] = 'https://www.meine-live-seite.de';
$config['stage_file_proxy.settings']['hotlink'] = FALSE;
$config['stage_file_proxy.settings']['origin_dir'] = 'sites/default/files';

Die Option hotlink ist interessant: Wenn du sie auf TRUE setzt, werden die Dateien nicht heruntergeladen, sondern direkt vom Live-Server eingebunden. Spart Speicher, braucht aber eine permanente Verbindung. Für die meisten Fälle ist FALSE (der Default) die bessere Wahl.

#Die perfekte Kombination: Stage File Proxy + Config Split

Hier wird es richtig elegant. Stage File Proxy gehört nur in deine Entwicklungs- und Staging-Umgebung – niemals auf Live. Und genau dafür gibt es Config Split.

Falls du Config Split noch nicht nutzt: Es erlaubt dir, Drupal-Konfigurationen umgebungsabhängig zu verwalten. Ein Config Split für die Dev-Umgebung könnte so aussehen:

#Config Split einrichten

1. Erstelle einen Config Split für deine Dev-Umgebung (falls noch nicht vorhanden):

drush config:set config_split.config_split.dev status TRUE

2. Füge stage_file_proxy zum Dev-Split hinzu. In der Config Split-Konfiguration unter /admin/config/development/configuration/config-split legst du fest, dass das Modul stage_file_proxy und seine Config stage_file_proxy.settings nur im Dev-Split aktiv sind.

3. In deiner lokalen settings.php aktivierst du den Split:

// settings.local.php
$config['config_split.config_split.dev']['status'] = TRUE;

4. Auf dem Live-System bleibt der Split deaktiviert – Stage File Proxy existiert dort schlicht nicht in der aktiven Konfiguration.

Das Ergebnis: Du machst drush cr, und je nach Umgebung ist Stage File Proxy an oder aus. Kein manuelles Aktivieren, kein Vergessen, kein Risiko auf Live.

#Praktische Tipps und Fallstricke

Nach einiger Zeit im produktiven Einsatz gibt es ein paar Dinge, die man wissen sollte:

#Performance

• Erster Seitenaufruf ist langsamer: Logisch – die Dateien müssen erst heruntergeladen werden. Danach sind sie lokal gecacht.
• Viele Bilder auf einer Seite: Wenn eine Seite 30 Bilder hat und keine davon lokal existiert, dauert der erste Aufruf entsprechend. Das ist normal und kein Bug.

#Authentifizierung

Falls dein Live-System hinter einem HTTP-Basic-Auth steht (Staging-Umgebung als Origin), kannst du die Credentials mitgeben:

$config['stage_file_proxy.settings']['origin'] = 'https://user:passwort@staging.meine-seite.de';

#Häufige Probleme

• HTTPS-Zertifikatsfehler: Wenn dein Origin ein selbst-signiertes Zertifikat nutzt, wird der Download fehlschlagen. Nutze ein valides Zertifikat oder konfiguriere die Verify-Option.
• Private Files: Stage File Proxy funktioniert standardmäßig mit dem Public-File-System. Für private Dateien braucht es zusätzliche Konfiguration.
• CDN vor dem Origin: Wenn deine Live-Dateien über ein CDN ausgeliefert werden, setze den Origin auf die tatsächliche Domain, nicht die CDN-URL.

#.gitignore nicht vergessen

Stelle sicher, dass sites/default/files in deiner .gitignore steht. Die heruntergeladenen Dateien gehören nicht ins Repository.

#Alternativen und wann Stage File Proxy sinnvoll ist

Stage File Proxy ist nicht für jedes Szenario die Antwort. Hier ein ehrlicher Überblick:

Stage File Proxy ist ideal wenn:

• Du lokal oder auf Staging entwickelst und echte Live-Daten brauchst
• Dein Projekt viele Medien hat und ein kompletter Sync unpraktisch ist
• Dein Team aus mehreren Entwicklern besteht, die alle eine lokale Umgebung betreiben
• Du von einem nicht mehr gepflegten Platzhalter-Modul migrieren willst

Weniger geeignet ist es wenn:

• Du komplett offline entwickeln musst (Zug, Flugzeug, schlechtes Hotel-WLAN)
• Dein Live-System nicht erreichbar ist oder strenge Firewall-Regeln hat
• Du mit extrem sensiblen Daten arbeitest, die nicht über das Netzwerk gezogen werden sollten

Andere Ansätze:

• rsync-Skripte: Für Teams, die einen vollständigen lokalen File-Stand brauchen, bleibt rsync eine Option – aber als bewusste Entscheidung, nicht als Notlösung.
• Docker-Volumes mit vorbereiteten Datensätzen: Für CI/CD-Pipelines, in denen ein definierter Testdatenbestand benötigt wird.

#Migration von media_placeholder

Wenn du aktuell noch drupal/media_placeholder im Einsatz hast, ist die Migration unkompliziert:

drush pm:uninstall media_placeholder
composer remove drupal/media_placeholder
composer require drupal/stage_file_proxy
drush en stage_file_proxy
drush config:set stage_file_proxy.settings origin "https://www.meine-live-seite.de"

Fünf Befehle, und du bist von einem toten Modul auf eine aktiv gepflegte, bessere Lösung umgestiegen. Kein Datenverlust, kein Risiko – die Platzhalter werden einfach durch echte Dateien ersetzt.

Stage File Proxy gehört in jedes Drupal-Projekt, das mit echten Inhalten arbeitet. Drei Befehle Setup, null Wartungsaufwand, und das Problem mit fehlenden Dateien in der Entwicklungsumgebung ist ein für alle Mal gelöst. Kombiniert mit Config Split hast du einen sauberen, automatisierten Workflow, der einfach funktioniert – ohne dass du je wieder darüber nachdenken musst.