TYPO3 11.5.25自定义后端布局模板文件找不到问题求助

问题现象 #

• 环境：TYPO3 11.5.25 + Bootstrap Package + 自定义站点包
• 本地开发时自定义后端布局运行正常，上传至服务器后报错：无法找到Standard/customHomepage.html模板文件，检查路径已包含自定义站点包和Bootstrap Package的模板目录
• 确认文件存在、站点包已添加到模板设置、Bootstrap Package自带布局正常可用；将模板文件名改为1.html后恢复正常，但文件名不一致导致本地与服务器同步困难

核心原因分析 #

1. 文件系统大小写敏感差异
   本地通常使用Windows（文件名不区分大小写），而服务器多为Linux系统（大小写严格区分）。如果后端布局配置中指定的模板名（如customHomepage）与实际文件名（如CustomHomepage.html）大小写不匹配，本地能正常识别，但服务器会判定文件不存在。

2. 后端布局与模板的映射配置错误
   Sitepackage Builder生成的后端布局需要在TS配置中明确关联模板文件名。如果templateName参数与实际模板文件名不匹配，或者模板路径优先级设置错误，会导致系统找不到对应模板。

3. 服务器缓存未清理
   上传文件后未清理TYPO3的配置缓存、模板缓存，系统仍读取旧的配置信息，无法识别新上传的模板文件。

解决与优化方案 #

• 统一文件名大小写
  严格保持后端布局配置中templateName的值与实际模板文件名的大小写完全一致，比如配置写templateName = customHomepage，则文件名必须为customHomepage.html，彻底避免大小写敏感问题。

• 检查并修正TS配置

  1. 打开自定义站点包中对应后端布局的TS配置文件（通常在Configuration/TypoScript/Page/BackendLayouts/目录下），确认templateName参数正确指向你的模板文件名：

     backend_layout {
         colCount = 1
         rowCount = 1
         // 省略布局列行配置
         templateName = customHomepage
     }
     

  2. 确保站点包的模板路径优先级高于Bootstrap Package，在站点包的主TS文件中设置：

     page {
         templateRootPaths {
             10 = EXT:custom/Resources/Private/Templates/Page/
             20 = EXT:bootstrap_package/Resources/Private/Templates/Page/
         }
     }
     

• 强制清理服务器缓存
  在TYPO3后端进入「系统」→「清除缓存」，选择「全部缓存」；若后端无法访问，可直接删除服务器typo3temp/目录下的缓存文件（注意保留.htaccess等系统文件）。

• 规范文件名管理
  自定义模板文件名与后端布局的key保持一致，比如后端布局key为custom_homepage，模板文件名设为CustomHomepage.html（或全小写customhomepage.html），统一命名规则后可避免同步时的文件名混乱。

内容的提问来源于stack exchange，提问作者Tim Döring