TYPO3 14 Upgrade-Checkliste — Schritt für Schritt migrieren

TYPO3 14 Upgrades scheitern selten am Core-Update — häufige Ursachen sind inkompatible Extensions, übersehene Deprecations und fehlende Rollback-Pläne. Diese Checkliste führt euch in drei Phasen (Analyse, Migration, Verifizierung) durch den gesamten Prozess — mit konkreten Composer-Befehlen und Prüfpunkten für jeden Schritt. So haltet ihr den Migrationsaufwand kalkulierbar und vermeidet Überraschungen auf Production. Die Checkliste ist für TYPO3-Integratoren und Agentur-Teams konzipiert, die ein bestehendes Projekt auf TYPO3 14 migrieren.

Den strategischen Überblick zu TYPO3 14 mit Release-Fahrplan und Feature-Einordnung findet ihr im TYPO3 14 Upgrade-Guide.

Upgrades scheitern selten am Core-Update selbst. Sie scheitern an ungeprüften Extensions, vergessenen Deprecations und fehlenden Rollback-Plänen.

Eine Checkliste macht den Prozess wiederholbar und reduziert die Abhängigkeit von einzelnen Entwicklern. Bei Agenturen, die mehrere TYPO3-Projekte betreuen, lässt sich derselbe Ablauf auf jedes Kundensetup anwenden. Das spart Zeit und verhindert, dass kritische Schritte übersprungen werden.

Die Analysephase bestimmt den Gesamtaufwand des Upgrades. Überspringt ihr diesen Schritt, werden Probleme erst während der Migration sichtbar — wenn Korrekturen deutlich teurer sind.

Extension-Audit durchführen

Listet alle installierten Packages auf und prüft deren TYPO3-14-Kompatibilität. Composer liefert euch die notwendigen Informationen direkt auf der Kommandozeile.

Kategorisiert jede Extension in eine von vier Gruppen:

• Kompatibel: TYPO3-14-Support bereits im aktuellen Release deklariert.
• Update verfügbar: Neuere Version mit TYPO3-14-Support auf Packagist vorhanden.
• Kein Update absehbar: Maintainer hat keine Kompatibilität angekündigt. Hier müsst ihr entscheiden: Fork, Alternative oder Eigenentwicklung.
• Eigenentwicklung: Euer eigener Code, den ihr selbst anpassen müsst.

Extensions der dritten Kategorie sind der größte Risikofaktor. Identifiziert sie frühzeitig und plant Alternativen.

PHP- und Datenbankversion prüfen

TYPO3 14 erfordert PHP 8.2 oder höher (empfohlen: 8.3/8.4) sowie MySQL 8.0+ oder MariaDB 10.4+. Prüft eure Server-Konfiguration bevor ihr den ersten Composer-Befehl ausführt. In DDEV-Umgebungen lässt sich die PHP-Version in der .ddev/config.yaml mit einer Zeile umschalten.

Deprecation-Log auswerten

Aktiviert das Deprecation-Logging in eurer aktuellen TYPO3-Installation und lasst es über mehrere Tage laufen. Jede Meldung im Log ist ein potenzieller Breaking Change in TYPO3 14. Arbeitet die Meldungen systematisch ab — idealerweise schon vor dem eigentlichen Upgrade.

• Wenn eine Extension aktiv gewartet wird und nur das Versionsconstraint fehlt → Maintainer kontaktieren oder Pull Request mit TYPO3-14-Kompatibilität einreichen.
• Wenn kein Update absehbar ist, aber der Quellcode überschaubar ist → Eigenen Fork erstellen und die Breaking Changes selbst auflösen.
• Wenn die Extension komplex ist und keine Alternative existiert → Budget für eine Eigenentwicklung einplanen und die Funktionalität gezielt reimplementieren.
• Wenn eine gleichwertige Alternative auf Packagist existiert → Extension austauschen und die Konfiguration migrieren.
• Wenn die Extension nur ein Feature liefert, das ihr kaum nutzt → Extension entfernen und auf die Funktionalität verzichten.

Die eigentliche Migration beginnt erst, wenn Phase 1 abgeschlossen ist und ihr einen klaren Überblick über den Aufwand habt. Führt alle Schritte in einer isolierten Testumgebung durch — niemals direkt auf Production.

Testumgebung aufsetzen

Klont eure Production-Umgebung in eine separate DDEV-Instanz oder einen Docker-Container. Importiert einen aktuellen Datenbank-Dump und stellt sicher, dass die Testumgebung den Production-Stand exakt widerspiegelt. Nur so sind die Testergebnisse belastbar.

Core-Update durchführen

Aktualisiert zuerst den TYPO3 Core, dann die Third-Party-Extensions. Das --with-all-dependencies-Flag stellt sicher, dass alle Abhängigkeiten konsistent aufgelöst werden. Nach dem Composer-Update: Datenbank-Schema aktualisieren und alle verfügbaren Upgrade Wizards ausführen.

Breaking Changes auflösen

TYPO3 14 entfernt APIs, die in TYPO3 13 als deprecated markiert waren. Typische Beispiele: entfernte Hook-Registrierungen, geänderte Interface-Signaturen und umbenannte Klassen. Das offizielle Changelog unter docs.typo3.org listet alle Breaking Changes mit Migrationspfad auf.

Die Migrationsphasen sind abgeschlossen, aber das Upgrade ist erst nach der Verifizierung fertig. Testet systematisch — nicht stichprobenartig.

Funktionale Tests

Geht jeden kritischen Workflow einmal vollständig durch:

• Frontend: Alle Seitentypen rendern korrekt (Startseite, Unterseiten, Landingpages, Detailseiten).
• Backend: Content-Editing, Seitenbaum-Navigation, Dateiverwaltung, Benutzerrechte.
• Formulare: Alle Kontaktformulare, Newsletter-Anmeldungen und Suchfelder funktionieren.
• Mehrsprachigkeit: Sprachumschaltung, Fallback-Logik und übersetzte Inhalte prüfen.
• Integrationen: APIs, Scheduler-Tasks, Cron-Jobs und externe Dienste verifizieren.

Performance-Vergleich

Messt die Ladezeiten der wichtigsten Seiten vor und nach dem Upgrade. Neue Core-Versionen können das Caching-Verhalten verändern. Vergleicht mindestens: Time to First Byte (TTFB), vollständige Seitenladezeit und Datenbank-Queryanzahl.

Redirect-Mapping verifizieren

Falls sich URL-Strukturen geändert haben, prüft das Redirect-Mapping vollständig. Fehlende oder fehlerhafte Redirects vernichten SEO-Rankings. Eine detaillierte Anleitung dazu findet ihr in unserer Redirect-Strategie für TYPO3-Relaunches.

Post-Go-Live-Monitoring

Überwacht euer System in den ersten 48 Stunden nach dem Go-Live aktiv. Prüft das TYPO3-Error-Log, die Server-Access-Logs und eure Monitoring-Tools. Reagiert sofort auf 500er-Fehler oder ungewöhnliche Performance-Einbrüche.

Fünf Probleme, die in der Praxis regelmäßig auftreten — und wie ihr sie vermeidet.

1. Extensions ohne composer.json

TYPO3 14 verlangt, dass jede Extension eine gültige composer.json besitzt — auch in Classic-Mode-Installationen. Ältere Extensions, die nie für Composer vorbereitet wurden, werden nicht mehr geladen. Lösung: Die fehlende composer.json mit korrektem type: typo3-cms-extension und extra.typo3/cms.extension-key ergänzen.

2. Datenbank-Collation-Konflikte

Bei Upgrades von älteren TYPO3-Versionen kann es zu Collation-Konflikten kommen, wenn Tabellen unterschiedliche Character-Sets verwenden. Prüft vor dem Upgrade die Datenbank-Collation und vereinheitlicht sie auf utf8mb4_unicode_ci.

3. Vergessene Scheduler-Tasks

CLI-Befehle und Symfony-Commands können sich zwischen Major-Versionen ändern. Prüft alle konfigurierten Scheduler-Tasks im TYPO3-Backend und stellt sicher, dass die registrierten Commands noch existieren. Entfernte Commands führen zu stillen Fehlern.

4. Third-Party-Extension Forks statt offizieller Versionen

Manche Projekte verwenden Forks oder gepatchte Versionen von Extensions. Diese werden beim Upgrade nicht automatisch aktualisiert und blockieren oft die Dependency-Auflösung. Prüft eure composer.json auf Repository-Einträge, die auf eigene Forks verweisen.

5. Nicht aktualisierte Site-Konfigurationen

TYPO3 14 kann Änderungen an der Syntax oder den verfügbaren Optionen in den Site-Konfigurationsdateien (config/sites/*/config.yaml) mit sich bringen. Vergleicht eure Konfigurationen nach dem Upgrade mit der Dokumentation und prüft, ob neue Pflichtfelder oder geänderte Defaults eure Seitenausgabe beeinflussen.

Fünf Maßnahmen, die ihr direkt nach einem erfolgreichen TYPO3 14 Upgrade umsetzen könnt:

1. OPcache zurücksetzen. Nach dem Upgrade den PHP OPcache leeren, damit der neue Code korrekt gecacht wird. In DDEV: ddev ssh -c "kill -USR2 1" oder Apache/PHP-FPM neu starten.

1. Cache-Warmup ausführen. Nach dem initialen cache:flush den Cache mit ddev typo3 cache:warmup gezielt aufbauen. Das verhindert, dass die ersten Seitenaufrufe nach dem Go-Live langsam sind.

1. Backend-Dashboard konfigurieren. TYPO3 14 bringt eine überarbeitete Dashboard Settings API. Richtet die Widgets so ein, dass eure Redakteure die für sie relevanten Informationen auf einen Blick sehen.

1. Content Blocks evaluieren. Prüft, ob bestehende Custom Content Elements als Content Blocks reimplementiert werden können. Das vereinfacht die Wartung langfristig und nutzt den neuen deklarativen Ansatz.

1. Deprecation-Logging aktiv lassen. Auch nach dem Upgrade auf TYPO3 14 produziert euer Code möglicherweise Deprecation-Meldungen — diesmal für TYPO3 15. Behebt sie laufend, statt sie bis zum nächsten Upgrade aufzuschieben.

Die Checkliste ist so konzipiert, dass ein erfahrenes Entwicklerteam das Upgrade eigenständig durchführen kann. Externe Unterstützung wird sinnvoll, wenn einer oder mehrere dieser Punkte auf euch zutreffen:

• Ihr habt mehr als 10 Third-Party-Extensions im Einsatz und der Extension-Audit zeigt mehrere inkompatible Packages.
• Eure Eigenentwicklungen nutzen APIs, die in TYPO3 14 als Breaking Changes entfernt wurden, und das Deprecation-Log ist umfangreich.
• Euer Team hat keine Erfahrung mit TYPO3-Major-Upgrades und der Prozess ist Neuland.
• Es gibt keinen dedizierten TYPO3-Entwickler im Haus, der den Upgrade-Prozess verantworten kann.
• Das Projekt läuft auf einer TYPO3-Version, die mehr als eine Major-Version zurückliegt (z. B. TYPO3 12 → 14).

In diesen Fällen könnt ihr TYPO3 14 Upgrade-Unterstützung anfragen — wir übernehmen die technische Umsetzung oder begleiten euer Team als Sparringspartner.