TYPO3 12/13 auf TYPO3 14 LTS upgraden – was wirklich zu tun ist

Von admin
Die Amr Webdesign Seite jetzt mit TYPO3 14 LTS

Praxisbericht aus einer Live-Migration – mit allen Stolperfallen, die die Dokumentation verschweigt

TYPO3 14 LTS ist am 21. April 2026 erschienen. Wer ein eigenes Fluid-Sitepackage betreibt – also kein Bootstrap Package, kein fertigkonfektioniertes Theme, sondern selbst gebaut – hat beim Upgrade eine Handvoll Dinge zu erledigen, die in der offiziellen Dokumentation entweder gar nicht oder nur zwischen den Zeilen stehen.

Dieser Artikel beschreibt den Weg von TYPO3 12 oder 13 LTS auf 14, mit dem konkreten Ziel: Frontend und Backend Layouts bleiben erhalten, alle Seiteneinstellungen bleiben erhalten, keine Seite muss neu konfiguriert werden.

Die Erkenntnisse kommen aus einer Live-Migration, nicht aus dem Labor.

Ein wunderschön aufgeräumtes und schnell arbeitendes Backend erwartet Euch bei TYPO3 LTS14
Ein wunderschön aufgeräumtes und schnell arbeitendes Backend erwartet Euch bei TYPO3 LTS14

Was sich grundsätzlich ändert

TYPO3 14 bringt keine revolutionären Brüche für bestehende Fluid-Installationen. FLUIDTEMPLATE läuft weiter, Fluid-Templates müssen nicht angefasst werden, CSS bleibt wie es ist. Der Aufwand steckt woanders: in der Art wie TYPO3 14 PageTSconfig lädt – und damit auch BackendLayouts.

Das Konzept heißt Site Sets. Wer bisher PageTSconfig per addPageTSConfig() in der ext_localconf.php geladen hat, wird beim Upgrade mit einem harten Fehler begrüßt. Und wer danach denkt, einfach einen Ordner umzubenennen, wird feststellen dass TYPO3 14 sehr eigene Vorstellungen hat wo Dateien liegen sollen.

Der Upgrade-Prozess Schritt für Schritt

Schritt 1 – Backup (Pflicht, kein Ermessen)

Bevor der typo3_src-Symlink angefasst wird: vollständiges Backup. Datenbank und Dateien.

mysqldump -u USER -p DATENBANKNAME > backup_$(date +%Y%m%d).sql

Wer Plesk nutzt: Backup Manager, komplette Domain sichern. Das dauert drei Minuten und erspart im Zweifel einen Tag.

Aufwand: Klein – 10–15 Minuten

Schritt 2 – typo3_src Symlink tauschen

Das eigentliche Core-Upgrade ist der schnellste Teil:

cd /pfad/zur/installation/
wget https://get.typo3.org/14.3/tar.gz -O typo3_src-14.3.0.tar.gz
tar -xzf typo3_src-14.3.0.tar.gz
rm typo3_src
ln -s typo3_src-14.3.0 typo3_src

Danach sofort im Install Tool alle Caches leeren – bevor die Seite im Browser aufgerufen wird.

Aufwand: Klein – 15 Minuten

Schritt 3 – Datenbank-Migration

TYPO3 14 bringt neue Tabellen mit, unter anderem sys_be_shortcuts_group. Ohne Migration erscheint im Frontend sofort ein TableNotFoundException. Nicht erschrecken – das ist kein Datenverlust, nur fehlende Tabellen.

Im Install Tool:

  1. Upgrade → Upgrade Wizard – alle Wizards der Reihe nach ausführen
  2. Maintenance → Analyze Database Structure – alle vorgeschlagenen SQL-Statements ausführen

Aufwand: Klein – 20–30 Minuten

Schritt 4 – Sitepackage anpassen

Hier steckt der eigentliche Aufwand. Drei Dateien müssen geändert, eine neue Ordnerstruktur muss angelegt werden.

4a – ext_emconf.php

Zwei Zeilen ändern:

// ALT
'version' => '1.0.0',
'typo3' => '12.0.0-13.99.99',

// NEU
'version' => '19.0.0',  // oder was auch immer die nächste Version ist
'typo3' => '14.0.0-14.99.99',

4b – composer.json

Alle typo3/cms-* Abhängigkeiten aktualisieren:

"require": {
    "typo3/cms-core": "^14.3",
    "typo3/cms-frontend": "^14.3",
    "typo3/cms-fluid": "^14.3",
    "typo3/cms-fluid-styled-content": "^14.3"
}

4c – ext_localconf.php – die zwei Breaking Changes

Das ist die Datei die beim Upgrade sofort crasht. Zwei Dinge müssen raus:

Breaking Change 1: GalleryProcessor existiert nicht mehr

Wer den bekannten TYPO3 13 Workaround für den width/height-Bug drin hat:

// DIESE ZEILEN KOMPLETT ENTFERNEN
$GLOBALS['TYPO3_CONF_VARS']['SYS']['Objects'][\TYPO3\CMS\Frontend\DataProcessing\GalleryProcessor::class] = [
    'className' => \TYPO3\CMS\Frontend\DataProcessing\FilesProcessor::class
];

Der GalleryProcessor ist in TYPO3 14 entfernt. TYPO3 wirft beim Laden der Extension sofort einen Fatal Error weil die Klasse nicht mehr existiert. Der FilesProcessor ist in TYPO3 14 ohnehin der Standard – der Workaround ist schlicht nicht mehr nötig.

Breaking Change 2: addPageTSConfig() existiert nicht mehr

// DIESE ZEILE ENTFERNEN
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPageTSConfig('...');

Die Methode ist in TYPO3 14 aus der ExtensionManagementUtility entfernt worden. PageTSconfig wird ab TYPO3 14 über Site Sets geladen – dazu gleich mehr.

Resultat ext_localconf.php – für viele Sitepackages bleibt nur noch das hier:

<?php
defined('TYPO3') or die('Access denied.');

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['mein_sitepackage'] =
    'EXT:mein_sitepackage/Configuration/RTE/Default.yaml';

Aufwand: Klein – 30 Minuten (inkl. Testen)

Schritt 5 – Site Sets einrichten (der entscheidende Schritt)

Das ist die größte konzeptuelle Änderung und der Punkt wo die meisten Agenturen Zeit verlieren – weil die Dokumentation hier dünn ist und man erst durch Ausprobieren auf die Lösung kommt.

Was sind Site Sets?

Site Sets sind in TYPO3 13.1 eingeführt worden und in TYPO3 14 der bevorzugte Weg um TypoScript, PageTSconfig und Einstellungen zu bündeln. Eine Extension registriert sich als Set, die Site trägt das Set als Dependency ein – und TYPO3 lädt automatisch was im Set-Ordner liegt.

Was TYPO3 14 automatisch lädt (und was nicht)

Hier die wichtigste Erkenntnis aus der Praxis:

Pfad Wird geladen?
Configuration/Sets/[name]/page.tsconfig ✅ Ja – automatisch
Configuration/Sets/[name]/setup.typoscript ✅ Ja – automatisch
Configuration/BackendLayouts/*.tsconfig ❌ Nein – nur per @import erreichbar
Configuration/PageTSconfig/*.tsconfig ❌ Nein – nur ohne Site Sets

Der Ordner Configuration/BackendLayouts/ wird von TYPO3 14 nicht automatisch geladen – auch wenn das aus der Struktur anderer Themes so aussieht. Die Dateien müssen per @import aus der page.tsconfig des Sets explizit eingebunden werden.

Die neue Struktur anlegen

1. Set-Ordner und config.yaml anlegen:

Configuration/Sets/mein_sitepackage/config.yaml

name: vendor/mein-sitepackage
label: 'Mein Sitepackage'

Der name muss exakt dem name-Feld in der composer.json entsprechen.

2. BackendLayouts-Ordner anlegen:

Configuration/BackendLayouts/default.tsconfig
Configuration/BackendLayouts/startseite.tsconfig
# usw. – die Dateien selbst bleiben unverändert, nur der Ordner ist neu

Die tsconfig-Dateien mit den BackendLayout-Definitionen können 1:1 aus dem alten TsConfig/Page/Mod/WebLayout/BackendLayouts/-Ordner kopiert werden. Inhalt bleibt identisch.

3. page.tsconfig im Set-Ordner anlegen:

Configuration/Sets/mein_sitepackage/page.tsconfig

# BackendLayouts
@import 'EXT:mein_sitepackage/Configuration/BackendLayouts/default.tsconfig'
@import 'EXT:mein_sitepackage/Configuration/BackendLayouts/startseite.tsconfig'
# weitere BackendLayouts...

# Weitere PageTS
@import 'EXT:mein_sitepackage/Configuration/TsConfig/Page/RTE.tsconfig'
@import 'EXT:mein_sitepackage/Configuration/TsConfig/Page/TCEFORM.tsconfig'
@import 'EXT:mein_sitepackage/Configuration/TsConfig/Page/TCEMAIN.tsconfig'

Wichtig: Explizite Imports, kein Wildcard (*.tsconfig). Wildcards in PageTSconfig-Imports sind nicht zuverlässig.

4. Site-Konfiguration aktualisieren:

In config/sites/[site-identifier]/config.yaml das Set als Dependency eintragen:

dependencies:
  - typo3/fluid-styled-content
  - typo3/fluid-styled-content-css
  - vendor/mein-sitepackage

Ohne diesen Eintrag lädt TYPO3 die page.tsconfig des Sets nicht – die BackendLayouts erscheinen dann nicht im Backend.

Aufwand: Mittel – 1–2 Stunden (abhängig von Anzahl der BackendLayouts und PageTS-Dateien)

Schritt 6 – Prüfen ob alles geladen wird

Nach Cache-Leeren im Backend prüfen:

Websites → Page TSconfig → Root-Seite → Tab „Aktive Page TSconfig“

Dort sollte mod.web_layout.BackendLayouts mit allen definierten Layouts erscheinen. Wenn nicht: Set nicht in der Site-Dependency eingetragen, oder Tippfehler im name der config.yaml.

Im Backend unter Seiteneigenschaften → Tab „Erscheinungsbild“ → Backend Layout auswählen: alle Layouts sollten jetzt zur Wahl stehen.

Aufwand: Klein – 15 Minuten

Gesamtaufwand im Überblick

Schritt Aufwand Kommentar
Backup Klein Nicht überspringen
Core-Tausch (typo3_src) Klein 15 Min.
Datenbank-Migration Klein 20–30 Min.
ext_emconf + composer.json Klein 15 Min.
ext_localconf.php bereinigen Klein 30 Min. inkl. Testen
Site Sets einrichten Mittel 1–2 Std.
Testen + Nacharbeiten Mittel 1–2 Std.
Gesamt Mittel 4–6 Stunden

Bei mehreren Sites auf einer Installation kommt pro Site ca. 30 Minuten für die Site-Konfiguration dazu.

Was sich nicht ändert

Das ist die gute Nachricht: der überwiegende Teil einer bestehenden Fluid-Installation muss nicht angefasst werden.

  • FLUIDTEMPLATE läuft in TYPO3 14 weiter – keine Migration zu PAGEVIEW erforderlich
  • Alle Fluid-Templates (Layouts, Templates, Partials) – unverändert
  • CSS und JavaScript – unverändert
  • TCA/Overrides (Custom Fields, Hero Slider etc.) – unverändert
  • TypoScript Setup und Constants – unverändert
  • BackendLayout-Definitionen (die tsconfig-Dateien selbst) – unverändert, nur Speicherort neu
  • Alle Seiteneinstellungen im Backend – bleiben erhalten, weil der Extension-Key identisch bleibt

Häufige Fehler und ihre Ursachen

„Loading ext_localconf.php failed“ → GalleryProcessor-Zeile oder addPageTSConfig noch drin. Beide entfernen.

„Table sys_be_shortcuts_group doesn’t exist“ → Datenbank-Migration nicht ausgeführt. Install Tool → Upgrade Wizard → Analyze Database.

BackendLayouts erscheinen nicht im Backend → Meistens eines von drei Problemen: Set nicht in Site-Dependency eingetragen, page.tsconfig fehlt im Set-Ordner, oder Tippfehler im name in config.yaml.

„Site Set nicht gefunden“ → Der Name in der Site config.yaml stimmt nicht mit dem name in Configuration/Sets/[name]/config.yaml überein. Beide müssen exakt gleich sein.

OPcache-Probleme → Nach dem Upgrade PHP OPcache leeren. In Plesk unter PHP-Einstellungen oder per SSH: php -r "opcache_reset();". Danach nochmal alle TYPO3-Caches leeren.

Fazit

Der Sprung von TYPO3 12 oder 13 auf 14 LTS ist für Fluid-Sitepackages gut machbar – vorausgesetzt man weiß wo die Fallstricke liegen. Die Breaking Changes in der ext_localconf.php sind schnell behoben. Der Löwenanteil der Arbeit steckt im Umstieg auf Site Sets für die PageTSconfig.

Wer das einmal sauber aufgesetzt hat, profitiert von einer deutlich klareren Struktur: PageTSconfig, TypoScript und Einstellungen liegen an einem definierten Ort, die Site-Konfiguration macht transparent was geladen wird.

Und wer mehrere Sites auf einer Installation betreibt – Ferienwohnungsportale, Agentur-Sites, Kundenprojekte – der freut sich, dass der Extension-Key identisch bleibt und keine einzige Seiteneinstellung neu gemacht werden muss.

Reinhold Packeisen – amr webdesign, Ostfriesland & Köln
April 2026