TYPO3 14 Upgrade-Checkliste — Schritt für Schritt migrieren
Upgrades scheitern fast nie am Core-Update. Sie scheitern an drei Extensions, die seit Jahren niemand angefasst hat, an Deprecations, die nie jemand gelesen hat, und daran, dass es keinen Weg zurück gibt. Diese Checkliste führt in drei Phasen durch den Prozess — Analyse, Migration, Verifizierung — mit den Befehlen, die tatsächlich funktionieren, und den Stellen, an denen wir selbst hängengeblieben sind. Für Entwickler und Agentur-Teams, die ein bestehendes Projekt auf TYPO3 14 LTS bringen.
Phase 1 — Analyse und Vorbereitung
Die Analysephase bestimmt den Gesamtaufwand. Wer sie überspringt, entdeckt dieselben Probleme später — dann aber mitten in der Migration, wo jede Korrektur teurer ist.
Extension-Audit. Listen Sie alle installierten Pakete auf und ordnen Sie jedes in eine von vier Kategorien:
- Kompatibel — v14-Support ist im aktuellen Release deklariert
- Update verfügbar — eine neuere Version mit v14-Support existiert
- Kein Update absehbar — der Maintainer hat nichts angekündigt
- Eigenentwicklung — Ihr eigener Code, den Sie selbst anpassen
Die dritte Kategorie ist Ihr Risiko. Alles andere ist Arbeit mit bekanntem Umfang.
PHP und Datenbank prüfen. TYPO3 14 verlangt mindestens PHP 8.2, empfohlen ist 8.4 oder neuer. Dazu MySQL 8.0+ oder MariaDB 10.4+. In DDEV genügt eine Zeile in der .ddev/config.yaml.
Deprecation-Log auswerten. Aktivieren Sie das Logging in der laufenden Installation und lassen Sie es mehrere Tage mitschreiben — nicht Stunden, denn selten genutzte Codepfade tauchen erst mit der Zeit auf. Jede Meldung ist ein potenzieller Breaking Change in v14.
- Extension-Audit
-
Der Extension-Audit ist die systematische Prüfung aller installierten Extensions auf Kompatibilität mit der Zielversion. Ziel ist, inkompatible Pakete, fehlende Updates und unwartete Extensions zu finden, bevor die Migration beginnt.
-
Abgrenzung
Anders als ein Composer-Update, das nur auflöst, was auflösbar ist, umfasst der Audit auch die Frage, was mit Extensions geschieht, für die es keine Lösung gibt — Fork, Ersatz, Eigenbau oder Verzicht.
Was tun mit inkompatiblen Extensions?
- Extension wird gepflegt, nur das Versionsconstraint fehlt → Maintainer kontaktieren oder Pull Request einreichen
- Kein Update absehbar, Quellcode überschaubar → eigenen Fork anlegen und Breaking Changes selbst auflösen
- Komplex und ohne Alternative → Budget für Eigenentwicklung einplanen
- Gleichwertige Alternative vorhanden → tauschen und Konfiguration migrieren
- Liefert nur ein Feature, das kaum genutzt wird → entfernen
Die letzte Option wird am häufigsten übersehen und ist oft die richtige. Prüfen Sie vor jeder Fork-Entscheidung, ob die Funktion überhaupt noch gebraucht wird.
Phase 2 — Migration
Die Migration beginnt erst, wenn Phase 1 abgeschlossen ist. Alle Schritte laufen in einer isolierten Umgebung — niemals auf Production.
Testumgebung aufsetzen. Klonen Sie Production in eine separate DDEV-Instanz: aktueller Datenbank-Dump, gleiche PHP-Version, gleiche Extensions. Weicht die Testumgebung ab, sind die Ergebnisse wertlos.
Core zuerst, Extensions danach. Das Flag --with-all-dependencies sorgt dafür, dass Composer alles konsistent auflöst, statt an einem Teilkonflikt zu scheitern.
Breaking Changes auflösen. TYPO3 14 entfernt APIs, die in v13 nur als veraltet markiert waren — Hook-Registrierungen, geänderte Interface-Signaturen, umbenannte Klassen. Das offizielle TYPO3-14-Changelog listet jede Änderung mit Migrationspfad.
Das v14-Changelog richtig lesen
Das Changelog ist die verbindliche Quelle für jedes Upgrade — und die einzige, die vollständig ist. Es liegt unter docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog-14.html und ist nach Versionen (14.0 bis 14.3) sowie nach vier Kategorien gegliedert:
- Breaking — entfernte oder geänderte APIs. Diese Einträge müssen Sie abarbeiten, sonst läuft das System nicht.
- Deprecation — noch funktionsfähig, aber in v15 weg. Das ist Ihre Arbeitsliste für das übernächste Upgrade.
- Feature — Neues, das Sie nutzen können, aber nicht müssen.
- Important — geändertes Verhalten ohne API-Bruch. Die tückischste Kategorie, weil nichts abstürzt, sich aber etwas anders verhält.
Die praktische Reihenfolge: Erst Breaking vollständig durchgehen, dann Important überfliegen, dann Deprecation in den Backlog. Features kommen zuletzt — sie lösen kein Upgrade-Problem.
Vier Einträge aus 14.0, die in der Praxis am häufigsten weh tun:
TypoScriptFrontendControllerwurde entfernt. Der mit Abstand folgenreichste Bruch. Jeder Zugriff auf$GLOBALS['TSFE']in eigenen Extensions, ViewHelpern oder Hooks muss ersetzt werden. Suchen Sie Ihre Codebasis gezielt danach ab, bevor Sie mit dem Upgrade anfangen — das ist erfahrungsgemäß der größte Einzelposten.- Das Feld
urlin der Tabellepagesist weg. Betrifft alte Installationen, die noch mit externen Verweisen über dieses Feld arbeiten. - Modals laufen auf nativem
dialogstatt Bootstrap. Relevant für alle, die eigene Backend-Module oder eigenes Backend-JavaScript pflegen. TCA type=uuidnutzt jetzt den Doctrine-GUID-Typ. Betrifft eigene TCA-Definitionen mit UUID-Feldern.
Für die Suche im eigenen Code gilt: Das Deprecation-Log der laufenden v13-Installation nennt Ihnen die Stellen, die konkret Sie betreffen. Das Changelog sagt Ihnen, was daraus in v14 geworden ist. Beide zusammen ergeben die Arbeitsliste — eines allein reicht nicht.
Schlägt Schritt 2 fehl, lesen Sie die Composer-Meldung genau: Sie benennt Paket und Versionskonflikt exakt. Lösen Sie Konflikte einzeln auf, statt mehrere Constraints gleichzeitig zu ändern — sonst wissen Sie am Ende nicht, welche Änderung geholfen hat.
Phase 3 — Verifizierung und Go-live
Das Upgrade ist nicht fertig, wenn es durchläuft, sondern wenn es geprüft ist. Systematisch, nicht stichprobenartig.
Funktionale Tests entlang der kritischen Abläufe: Frontend-Rendering aller Seitentypen, Backend-Bearbeitung, Seitenbaum, Dateiverwaltung, Benutzerrechte, sämtliche Formulare, Sprachumschaltung samt Fallback-Verhalten, Scheduler-Tasks und externe Schnittstellen.
Performance vergleichen. Messen Sie vorher und nachher — Time to First Byte, vollständige Ladezeit, Anzahl der Datenbankabfragen. Neue Core-Versionen ändern das Caching-Verhalten, und ein Rückschritt fällt ohne Vergleichswert erst auf, wenn sich jemand beschwert.
Redirects prüfen. Haben sich URL-Strukturen geändert, muss das Mapping vollständig sein. Wie das geht, steht in der Redirect-Strategie.
Nach dem Go-live 48 Stunden aktiv beobachten: Error-Log, Access-Logs, Monitoring. Auf 500er und Performance-Einbrüche sofort reagieren.
Die vollständige Upgrade-Checkliste
- Alle installierten Extensions mit Versionen auflisten und dokumentieren
- Jede Extension auf v14-Kompatibilität prüfen (Packagist, TER, Repository)
- Extensions kategorisieren: kompatibel, Update verfügbar, kein Update, Eigenentwicklung
- PHP-Version des Zielservers prüfen (mindestens 8.2, empfohlen 8.4+)
- Datenbankversion prüfen (MySQL 8.0+ oder MariaDB 10.4+)
- Deprecation-Logging aktivieren und über mehrere Tage auswerten
- Upgrade mit --dry-run testen, um Konflikte vorab zu erkennen
- Vollständiges Datenbank-Backup erstellen — vor jedem Versuch, nicht nur vor dem ersten
- fileadmin sichern und den Backup-Pfad dokumentieren
- Isolierte Testumgebung mit aktuellem Dump aufsetzen
- Core mit --with-all-dependencies aktualisieren, danach die übrigen Extensions
- extension:setup ausführen (ohne --extension-Filter)
- Alle Upgrade Wizards durchlaufen lassen
- Breaking Changes in Eigenentwicklungen auflösen
- Mit extension:list prüfen, ob alle Extensions geladen werden
- Frontend-Rendering aller Seitentypen und Inhaltselemente testen
- Backend-Bearbeitung, Seitenbaum, Dateiverwaltung und Rechte testen
- Formulare, Suche und interaktive Elemente testen
- Mehrsprachigkeit prüfen: Umschaltung, Fallbacks, übersetzte Inhalte
- Scheduler-Tasks, Cron-Jobs und API-Integrationen verifizieren
- Redirect-Mapping erstellen und vollständig prüfen
- Rollback-Plan schriftlich festhalten, mit konkreten Schritten
- Redaktion über die Backend-Änderungen informieren
- Nach dem Go-live mindestens 48 Stunden Logs und Performance überwachen
Fünf Stolperfallen aus der Praxis
1. Extensions ohne composer.json. Werden in v14 nicht mehr geladen, auch im Classic Mode. Fehlende Datei mit korrektem type und extension-key ergänzen.
2. Collation-Konflikte. Bei Upgrades von älteren Versionen kollidieren Tabellen mit unterschiedlichen Zeichensätzen. Vorher prüfen und auf utf8mb4_unicode_ci vereinheitlichen.
3. Vergessene Scheduler-Tasks. CLI-Kommandos ändern sich zwischen Hauptversionen. Ein Task, dessen Command nicht mehr existiert, schlägt still fehl — niemand merkt es, bis jemand nach dem Export fragt.
4. Forks statt offizieller Versionen. Gepatchte Extensions aus eigenen Repositories aktualisieren sich nicht mit und blockieren regelmäßig die Auflösung. Prüfen Sie die repositories-Einträge Ihrer composer.json.
5. Unveränderte Site-Konfigurationen. Neue Pflichtfelder oder geänderte Standardwerte in config/sites/*/config.yaml können die Ausgabe beeinflussen. Nach dem Upgrade mit der Dokumentation abgleichen.
Fünf Dinge direkt nach dem Upgrade
1. OPcache zurücksetzen, damit der neue Code nicht gegen zwischengespeicherten alten läuft — in DDEV genügt ddev restart. 2. Cache-Warmup ausführen (ddev typo3 cache:warmup), damit die ersten Aufrufe nach dem Go-live nicht die langsamsten sind. 3. Backend-Dashboard einrichten — v14 bringt eine überarbeitete Dashboard-API; die Standardwidgets sind selten die, die Ihre Redaktion braucht. 4. Content Blocks evaluieren: Lassen sich bestehende Custom-Elemente deklarativ neu bauen? Details im Artikel zu Content Blocks. 5. Deprecation-Logging aktiv lassen. Ihr Code produziert jetzt Meldungen für TYPO3 15. Laufend beheben ist ungleich billiger, als sie bis zum nächsten Major-Upgrade zu sammeln.
Häufig gestellte Fragen
Zuerst prüfen, ob auf Packagist oder im TER ein Update existiert. Wenn nicht, gibt es vier Wege: einen eigenen Fork pflegen, eine gleichwertige Alternative einsetzen, die Funktion selbst neu bauen — oder auf sie verzichten, wenn sie kaum genutzt wird. Entscheidend ist, dass diese Analyse vor der Migration stattfindet, nicht mittendrin.
Technisch ja, sinnvoll nein. Wizards migrieren Datenstrukturen und Konfigurationen, die die neue Version voraussetzt. Übersprungene Wizards führen zu Fehlern, die erst Wochen später auffallen und dann schwer zuzuordnen sind. Führen Sie alle empfohlenen aus und dokumentieren Sie, welche Sie bewusst ausgelassen haben.
Primärquelle ist das Deprecation-Log der laufenden Installation — jede Meldung nennt Klasse oder Methode und den empfohlenen Ersatz. Ergänzend listet das offizielle Changelog alle Breaking Changes mit Migrationspfad. Durchsuchen Sie Ihren Code gezielt nach den dort genannten Klassen.
Mindestens 48 Stunden — in dieser Zeit laufen die meisten Seitentypen, Formulare und Integrationen durch echte Nutzung. Bei hohem Traffic oder vielen Schnittstellen ist eine Woche angemessen.
Ja. Ein Major-Upgrade ohne Testumgebung ist ein vermeidbares Risiko, und die Umgebung ist in DDEV in Minuten aufgesetzt. Wichtig ist, dass sie den Produktivstand exakt abbildet — gleiche PHP-Version, gleiche Datenbank, gleicher Extension-Stand. Eine ungefähre Kopie liefert ungefähre Ergebnisse.
Ja, aber Sie arbeiten dann die Breaking Changes zweier Hauptversionen gleichzeitig ab. Der Zwischenschritt über v13 verteilt den Aufwand und macht Fehler leichter zuordenbar. Bei überschaubaren Installationen ist der direkte Weg vertretbar — bei vielen Eigenentwicklungen selten.
Wann sich Unterstützung lohnt
Diese Checkliste ist so geschrieben, dass ein erfahrenes Team das Upgrade selbst durchführen kann. Sinnvoll wird Hilfe, wenn:
- viele Eigenentwicklungen im Einsatz sind, deren Kompatibilität unklar ist
- der Extension-Audit mehrere Pakete ohne absehbares Update ergibt
- keine Testumgebung existiert und auch keine aufgesetzt werden kann
- das Upgrade mit einem Relaunch oder Redesign zusammenfallen soll
- Ihr System bereits aus dem Support gefallen ist und unter Zeitdruck steht
