Der Sprung auf TYPO3 14: vier Stellen, die vor dem Umschalten angefasst werden müssen – und warum der Deploy fast mitten im Kopieren gescheitert wäre

Der Sprung auf TYPO3 14

TYPO3 14 ist die neue Langzeit-Version. Als erste Kundenwebsite haben wir den zweisprachigen Auftritt eines Industrie- und Agrarunternehmens von TYPO3 13 auf 14 gehoben: 61 Seiten in Deutsch und Englisch, eine Produktübersicht und neun eigens entwickelte Inhaltselemente. Umgestellt wurde am 15. Oktober 2026 um 22:47 Uhr, nachts, in einem Schritt. Danach waren alle Seiten in beiden Sprachen unverändert erreichbar.

Dieser Beitrag ist als Leitfaden für alle gedacht, die das Upgrade noch vor sich haben. Er zeigt, welche Änderungen in TYPO3 14 Webserver, Sitepackage und Datenbank wirklich betreffen und was erst bei einer Generalprobe auf echten Produktionsdaten auffällt. Und er erklärt, warum der riskanteste Fehler des ganzen Projekts gar nicht in TYPO3 lag, sondern im Deploy-Skript.

Die Herausforderung

Ein Versionssprung von einer Langzeit-Version zur nächsten ist kein composer update. Für dieses Projekt galten von Anfang an klare Randbedingungen:

• Die Live-Seite bleibt auf TYPO3 13, bis umgeschaltet wird. Die Redaktion arbeitet in der Zwischenzeit ganz normal weiter.
• Ein Schritt, nachts, höchstens fünf Minuten. Das haben wir dem Kunden schriftlich zugesagt. Wir sind davon ausgegangen, dass die Seite erreichbar bleibt.
• Für Besucher ändert sich nichts. Jede Seite muss in beiden Sprachen nach dem Upgrade genauso aussehen wie vorher.
• Server und Hosting bleiben unverändert. Das Upgrade läuft über den bestehenden automatischen Deploy: Sicherung, Build, Upgrade-Wizards, Smoke-Check.
• Ein vorbereiteter Rückweg. Falls nach dem Umschalten etwas nicht stimmt, muss klar sein, mit welchen Befehlen der alte Stand zurückkommt.

Unsere Lösung

Wir haben das Upgrade in acht Schritte zerlegt und auf zwei Spuren verteilt. Alles, was schon mit TYPO3 13 funktioniert, ging vorab schrittweise live. Für Besucher und Redaktion änderte sich dabei nichts. Alles, was nur mit TYPO3 14 funktioniert, entstand auf einem eigenen Integrationszweig. Dort wurde es auf einer Kopie der Datenbank getestet und erst mit dem Umschalten live geschaltet. So blieb für den Umschaltabend nur noch das übrig, was wirklich nicht früher gehen konnte.

1. Vorarbeit unter TYPO3 13: keine einzige Deprecation mehr

Der erste Schritt lief noch komplett auf Version 13. Unser Ziel: Das Sitepackage benutzt nichts mehr, was TYPO3 13.4 als veraltet meldet. Als Prüfung dienten das Deprecation-Log beim Aufruf aller Sitemap-URLs in beiden Sprachen, ein Rundgang durch das Backend und der Extension-Scanner im Install Tool. Am Ende verwies kein einziger Log-Eintrag mehr auf eigenen Code.

Dabei kamen zwei Dinge zutage, die niemand gesucht hatte. In der Datenbank lag noch eine TypoScript-Bedingung in der alten Syntax ([globalVar = GP:L=1]). Sie war längst wirkungslos, schrieb aber bei jedem ungecachten Seitenaufruf einen Fehler ins Log. Ein einmaliger Upgrade-Wizard hat sie beim nächsten Deploy entfernt. Und die Seiten lieferten nie den Namen der Website für das Teilen in sozialen Netzwerken (og:site_name), weil der alte Lookup ins Leere lief. Beim Vergleich aller 61 Seiten vor und nach der Änderung war das die einzige Abweichung: eine zusätzliche Zeile pro Seite.

Was sich unter 13 nicht ändern ließ, ohne 13 zu brechen, kam auf eine Liste – mit Datei, Zeile und Begründung. Diese Liste war später die Arbeitsgrundlage für TYPO3 14.

2. Erste Stelle: der Webserver

In TYPO3 14 gibt es den Backend-Einstieg /typo3/index.php nicht mehr. Unsere nginx-Konfiguration leitete das Backend aber genau dorthin. Mit TYPO3 14 hätte /typo3/ deshalb mit 404 geantwortet: kein Login, keine Redaktion. Die Lösung ist eine Zeile, und sie funktioniert schon unter 13. Deshalb ging sie vorab live:

location /typo3 {
    try_files $uri /index.php$is_args$args;
}

Spannend wurde es bei dem, was an der alten Regel hing. Das Backend bekam ein höheres Speicherlimit von 1 GB für Dateioperationen. Dieses Limit hing an der nginx-Regel für PHP-Dateien unter /typo3/. Seit das Backend über /index.php läuft, greift diese Regel nicht mehr. Wir erkennen Backend-Anfragen jetzt an der aufgerufenen Adresse und vergeben das Limit danach.

Die Qualitätssicherung hat dabei eine echte Sicherheitslücke gefunden, bevor sie live gehen konnte. Die allgemeine PHP-Regel reicht die Client-Adresse aus dem Header X-Forwarded-For weiter, und den kann jeder Client selbst setzen. Hätte das Backend diese Adresse übernommen, wäre die Login-Sperre von TYPO3 (fünf Fehlversuche in 15 Minuten pro Adresse) wirkungslos gewesen: Ein Angreifer hätte einfach bei jedem Versuch einen neuen Wert mitgeschickt. Das Backend sieht deshalb weiterhin die Adresse der tatsächlichen Verbindung. Bis die Erkennung dicht war, brauchte es drei Review-Runden, denn auch //typo3/login und /typo3#x führen ins Backend. Zum Schluss haben wir 1.160 Varianten von Anfrage-Adressen durchgeprüft. Keine einzige führte noch mit einer selbst gewählten Adresse ins Backend.

Das Install Tool liegt in TYPO3 14 nicht mehr unter /typo3/install.php, sondern unter /?__typo3_install. Eine Sonderregel dafür haben wir bewusst nicht gebaut. Wir haben stattdessen gemessen: Umgebungsprüfung, Datenbankabgleich und Wizard-Liste kommen mit höchstens 36 MB aus, also weit unter dem normalen Limit von 512 MB.

3. Zweite Stelle: das Sitepackage

Auf dem Integrationszweig haben wir zuerst TYPO3 und alle Abhängigkeiten auf Version 14 gehoben. Danach liefen alle Seiten ohne Fehler. Fertig war das Sitepackage damit aber noch nicht:

• composer.json ersetzt ext_emconf.php. Die Metadaten der Extension stehen in TYPO3 14 nur noch in der composer.json. Die alte Datei wurde gelöscht.
• FlexForms pro Inhaltstyp. Die neun eigenen Inhaltselemente und das Produkt-Plugin hängen ihre FlexForms jetzt direkt an den jeweiligen Inhaltstyp. Der bisherige Weg ist veraltet und fällt mit Version 15 weg.
• Backend-Vorschauen. Die Vorschau-Templates im Seitenmodul bekommen in TYPO3 14 kein rohes Datenbank-Feld mehr, sondern ein Record-Objekt. Bei allen neun Elementen war die Datensatz-ID deshalb leer, und das Backend zeigte nur noch die Standardvorschau. Die Templates lesen jetzt aus dem Record-Objekt.
• Fließtext-Links. TYPO3 14 liefert die bisherigen Voreinstellungen für Rich-Text nicht mehr mit. Ohne Anpassung hätten sich 32 externe Links auf 18 Seiten im selben Fenster geöffnet statt in einem neuen, und Tabellen hätten ihre CSS-Klasse verloren. Wir haben die Einstellungen im eigenen TypoScript wiederhergestellt.
• Upgrade-Wizards im neuen Namensraum. Die Basisklassen für eigene Wizards sind in TYPO3 14 umgezogen, und für den alten Namen gibt es keinen Alias. Das ist keine Deprecation, sondern ein fataler Fehler, sobald die Klasse geladen wird.
• Kleinkram mit Frist. Extbase-Attribute, Suchfelder im TCA und Spalten-Kennungen in den Backend-Layouts. Das alles funktioniert noch, wird aber in Version 15 Pflicht.

Danach waren alle 61 Seiten in TYPO3 13 und 14 identisch, bis auf Cache-Busting-Parameter und eine Leerzeile im <head>. Alle Formulare im Backend ließen sich öffnen und speichern.

4. Dritte Stelle: die Datenbank

Die erste Überraschung kam beim allerersten Kontakt mit der Datenbank. Auf einem 13er-Datenbestand startet in TYPO3 14 kein einziger Kommandozeilen-Befehl. Jeder bricht ab mit Unknown column 'user_settings'. Der automatische Deploy wäre am Umschaltabend genau an dieser Stelle hängen geblieben. Unser Deploy-Skript hat deshalb einen eigenen Schritt bekommen, der diese eine Spalte vor dem Austausch des Containers anlegt. Auf der Produktion lief er schon vorab mit, unter TYPO3 13.

Das Schema selbst haben wir über dieselbe Core-Schnittstelle abgeglichen, die auch das Install Tool benutzt. Das von vielen gewohnte database:updateschema stammt aus einer Zusatz-Extension, die hier nicht installiert ist. Angewendet wurden 46 nicht-destruktive Änderungen. 137 destruktive Änderungen sind bewusst unterblieben: Sie stehen im Ablaufplan, damit niemand sie versehentlich ausführt.

Die zweite Überraschung steckte in einem Upgrade-Wizard. pageDoktypeLinkMigration überträgt das Linkziel von Verweis-Seiten in ein neues Feld, aber nur für sichtbare Seiten. Das destruktive Schema-Update entfernt das alte Feld später. Betroffen waren zehn versteckte Altseiten: Kopien aus den Jahren 2019 und 2020, von denen fünf ein Ziel trugen, alle auf einen Server, den es längst nicht mehr gibt. Ihre sichtbaren Gegenstücke wurden sauber migriert. Wir haben den Verlust nicht stillschweigend hingenommen, sondern bewusst entschieden und im Ablaufplan festgehalten.

Eine Generalprobe ist nur so gut wie die Daten, auf denen sie läuft.

5. Vierte Stelle: die Generalprobe auf echten Daten

Die erste Generalprobe lief auf einem Datenbestand, der einige Tage alt war, und die Qualitätssicherung hat sie zurückgewiesen. Der Grund: Die drei Backend-Zugänge, die der Kunde inzwischen angelegt hatte, waren darin nicht enthalten. Damit wären ausgerechnet die Wizards, die persönliche Benutzereinstellungen migrieren, am Umschaltabend zum ersten Mal gelaufen. Wiederholt wurde die Probe auf einem frischen, nur lesend gezogenen Abzug der Produktionsdatenbank, in einer komplett getrennten Umgebung:

• Der Deploy, nicht ein Nachbau. Die Schritte des echten Deploy-Skripts liefen in der Reihenfolge der Pipeline, ohne einen einzigen Handgriff dazwischen. Nach 7 Sekunden war die Umgebung bereit, und alle 9 Upgrade-Wizards meldeten OK.
• Jede Seite, beide Sprachen. Wir haben alle Seiten aus der Sitemap, die Sitemap selbst, robots.txt und Fehlerseiten mit der Live-Seite verglichen. Abweichungen gab es nur bei der Adresse der Unter-Sitemap, und die geht auf eine bekannte Core-Änderung zurück. Daraus folgt: In der Search Console nur noch die Index-Sitemap einreichen.
• Backend als Redakteur, nicht als Admin. Ein Redakteur ohne Admin-Rechte hat einen Text, ein eigenes Inhaltselement und ein Produkt bearbeitet und gespeichert, eine Datei hochgeladen und eine Seite angelegt und wieder gelöscht. Zusätzlich haben sich zwei migrierte Produktions-Zugänge angemeldet, und ihre persönlichen Einstellungen waren erhalten.
• Unterbrechung gemessen, nicht geschätzt. Die Seite war 6,2 Sekunden nicht erreichbar.

• Rückweg geprobt. Wir haben die Datenbank zurückgespielt und den alten Stand neu deployt, beides mit genau den Befehlen aus dem Ablaufplan.

• 61 Seiten in zwei Sprachen verglichen
• 9 Upgrade-Wizards, alle ohne Fehler
• 137 destruktive Schema-Änderungen bewusst ausgelassen
• 6,2 s Unterbrechung in der Probe

Ein Nebenfund hatte mit TYPO3 14 gar nichts zu tun. Seit einem Serverumzug wenige Tage zuvor war TYPO3 auf ImageMagick eingestellt, im Container gab es aber nur GraphicsMagick. Neu berechnete Bildgrößen wurden deshalb in voller Originalgröße ausgeliefert. Der Fehler wurde noch vor dem Upgrade auf der Produktion behoben.

6. Der Beinahe-Unfall: rsync --delete

Am Vorabend des geplanten Umschaltens scheiterten drei normale Deploys hintereinander, und zwar an einer einzigen Datei. Eine Redakteurin oder ein Redakteur hatte zum Testen eine Seite auf oberster Ebene angelegt und eine Minute später wieder gelöscht. TYPO3 legt in so einem Fall automatisch eine Site-Konfiguration an. Das Verzeichnis gehört dem Container-Benutzer und bleibt auch nach dem Löschen der Seite liegen. Der Deploy synchronisiert die Dateien mit rsync --delete auf den Server und will dieses unbekannte Verzeichnis entfernen. Das darf er nicht, und er bricht mit Exit-Code 23 ab.

Das Tückische ist der Zeitpunkt. rsync bricht ab, nachdem die Dateien kopiert sind. Bei einem normalen Release ist das ärgerlich, aber harmlos: Der alte Container läuft einfach weiter. Am Umschaltabend wäre genau das fatal gewesen. Das TYPO3-14-Sitepackage hätte dann im Verzeichnis gelegen, das in den laufenden TYPO3-13-Container eingebunden ist, und kein Wizard wäre gelaufen. Die Qualitätssicherung hat diesen Zustand in einer Probe versehentlich nachgestellt. Die Kommandozeile von TYPO3 13 starb sofort mit Interface "TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface" not found. Die Website lieferte nur noch aus ihren Caches aus.

Die Qualitätssicherung hat daraufhin einen Release-Stopp gesetzt: Kein Umschalten, solange der Deploy nicht wieder grün ist. Behoben wurde es auf zwei Wegen. Das verwaiste Verzeichnis wurde entfernt, und der Deploy schließt automatisch erzeugte Site-Konfigurationen grundsätzlich vom Abgleich aus. Scheitert rsync trotzdem einmal, meldet der Job klar, dass er nach dem Kopieren stehen geblieben ist und die alten Container noch laufen. Im Test endete der alte Ablauf mit Exit-Code 23, der neue mit 0, und alle anderen veralteten Dateien wurden weiterhin gelöscht.

Unser Ablaufplan kannte die Vorab-Prüfung „letzter Deploy war grün“ schon vorher. Hier hat sie sich bezahlt gemacht.

7. Der Umschaltabend

Der Ablauf am 15. Oktober war am Ende unspektakulär, und genau so sollte es sein:

1. Vorab-Prüfungen: Produktion auf TYPO3 13.4 ohne offene Wizards, die letzte Deploy-Pipeline grün, keine aktive Backend-Sitzung in der letzten halben Stunde.
2. Sicherung: Datenbank-Abzug vor dem Deploy. Das ist der Wiederherstellungspunkt für jeden Rückweg.
3. Build: Das neue Image wird in 52 Sekunden gebaut, bevor irgendetwas gestoppt wird.
4. Schema-Vorbereitung: Die fehlende Spalte war schon vorhanden. Nichts zu tun.
5. Container-Austausch: 23 Sekunden vom Start des Austauschs bis zur Betriebsbereitschaft.
6. Upgrade-Wizards: 9 gefunden, alle OK, wie in der Generalprobe.
7. Smoke-Check: Startseite, englische Startseite, Sitemap und Backend-Login antworten mit 200.

Danach haben wir die Seiten stichprobenartig geprüft, darunter eine Produktseite, eine 404-Seite, die Weiterleitungen der Nebendomain, die Sprachverknüpfungen und die Bildberechnung. Außerdem haben wir die Logs durchgesehen: kein fataler Fehler, keine Deprecation. Den Rückweg, also Datenbank-Abzug zurückspielen und Merge-Commit zurücknehmen, hatten wir mit den exakten Befehlen vorbereitet. Gebraucht haben wir ihn nicht.

Das Ergebnis

• TYPO3 14 läuft seit dem 15. Oktober 2026, 22:47 Uhr, nachts umgestellt, wie mit dem Kunden vereinbart.
• Alle Seiten in Deutsch und Englisch sind unverändert erreichbar, mit Bildern, Produktübersichten und Sprachwechsel.
• Die Redaktion arbeitet weiter wie gewohnt. Zugänge und persönliche Einstellungen wurden übernommen.
• Nur Sekunden statt Minuten: 6,2 Sekunden Unterbrechung in der Probe, zugesagt waren höchstens fünf Minuten.
• Ein Sitepackage ohne Deprecations, dadurch ist der Weg zu TYPO3 15 kürzer.
• Ein robusterer Deploy: Eine Aktion im Backend kann ihn nicht mehr blockieren, und wenn er abbricht, meldet er klar, wo.

Fazit

Der Weg auf TYPO3 14 führt über vier Stellen, die man vor dem Umschalten angefasst haben muss: den Webserver, das Sitepackage, die Datenbank und eine Generalprobe auf echten Daten. Keine davon ist für sich spektakulär, aber jede kann den Umschaltabend allein scheitern lassen. Unsere wichtigste Lehre stammt aber nicht aus dem Changelog. Ein Upgrade ist so sicher wie der Deploy, der es ausliefert. Prüfen Sie deshalb vor dem Umschalten nicht nur TYPO3, sondern auch, ob Ihr Deploy auf halbem Weg stehen bleiben kann.