Typo3 v11升级v12后升级向导无法运行的问题及解决

问题现象 #

• 从TYPO3 11.5.39（11LTS）通过Composer升级到12.4.19（12LTS）后，点击升级向导弹出错误提示，无法正常运行
• 多数场景下系统日志无有效报错内容，仅偶发缓存文件写入失败的异常

排查结论 #

按TYPO3 v11官方文档创建的本地模板包，未被v12内置的「Scan Extension Files」工具检测出兼容性问题，但实际存在代码兼容缺陷：本地模板包的local_packages/site-template/ext_localconf.php文件中，仍使用v11及更早版本的入口校验代码defined('TYPO3_MODE') || die();，而该常量在TYPO3 12中已被移除，替换为TYPO3常量。

解决方案 #

通过ssch/typo3-rector工具自动修复代码兼容性问题，步骤如下：

1. 安装开发依赖包：

   composer require --dev ssch/typo3-rector
   

2. 初始化Rector的TYPO3适配配置：

   vendor/bin/typo3-init
   

3. 执行代码自动修复：

   vendor/bin/rector process
   

   该命令会自动将ext_localconf.php中的旧校验代码替换为defined('TYPO3') || die();，修复后升级向导即可正常运行。

内容的提问来源于stack exchange，提问作者oheil