TYPO3更新扩展时如何防止自定义修改的代码数据被覆盖

不要直接修改bootstrap_package或Pizpalue的原文件——只要你动了第三方扩展目录下的内容，下次不管是TER更新还是composer拉新版本，所有改动都会被直接覆盖，没有例外。正确方案是搭建独立的自定义站点扩展（sitepackage），所有修改、新增文件全放在这个独立扩展里，利用TYPO3原生的加载优先级机制覆写第三方扩展的配置、模板和逻辑，完全不碰原扩展文件，更新时不会丢失任何自定义内容。

第一步：创建自定义sitepackage扩展 #

• 在typo3conf/ext/目录下新建自己的扩展目录，比如命名为my_sitepackage，只需要搭最基础的扩展结构即可：
  • 根目录新建ext_emconf.php，声明扩展基本信息，依赖项填写bootstrap_package、pizpalue，确保加载顺序在两个第三方扩展之后
  • 如果是composer模式安装的TYPO3，根目录补一个composer.json配置PSR-4自动加载规则
  • 按需创建对应功能目录：Configuration/TypoScript/（放TypoScript配置）、Resources/Private/Templates//Layouts//Partials/（放HTML模板）、Resources/Public/Css//Js/（放静态资源）、Classes/（放PHP代码），根目录直接放ext_tables.sql、ext_localconf.php等全局配置文件
• 进入后台扩展管理模块，激活新建的my_sitepackage，确认它在扩展加载列表里排在bootstrap_package、Pizpalue之后——TYPO3加载扩展时靠后位置的配置优先级更高，只有顺序对了覆写才会生效。

第二步：不同类型文件的自定义操作 #

HTML模板文件（Templates/Layouts/Partials） #

• 找到你要修改的原扩展HTML文件，完整复制到自己sitepackage的对应路径下，路径结构必须和原扩展完全一致。
  举个例子：原文本内容元素模板路径是bootstrap_package/Resources/Private/Templates/ContentElements/Text.html，你就把文件复制到my_sitepackage/Resources/Private/Templates/ContentElements/Text.html，后续所有修改直接在复制过来的文件上操作即可，TYPO3会自动优先加载你扩展里的模板。
• 新增自定义内容元素的HTML模板，直接放到sitepackage对应模板目录下，后续通过TypoScript注册即可。
• 记得在自己的TypoScript配置里添加模板根路径，优先级数值要比原扩展的配置大：

  lib.contentElement.templateRootPaths {
    100 = EXT:my_sitepackage/Resources/Private/Templates/ContentElements/
  }
  lib.contentElement.partialRootPaths {
    100 = EXT:my_sitepackage/Resources/Private/Partials/ContentElements/
  }
  lib.contentElement.layoutRootPaths {
    100 = EXT:my_sitepackage/Resources/Private/Layouts/ContentElements/
  }
  

CSS/JS等静态资源 #

• 不建议直接复制原扩展的整份CSS/JS文件修改，维护成本很高。小调整直接写独立的自定义CSS/JS文件，放到sitepackage的Resources/Public/对应目录下，通过TypoScript引入，设置高优先级覆盖原有样式即可：

  page.includeCSS {
    myCustomStyle = EXT:my_sitepackage/Resources/Public/Css/custom.css
    myCustomStyle.forceOnTop = 1
  }
  page.includeJSFooter {
    myCustomScript = EXT:my_sitepackage/Resources/Public/Js/custom.js
    myCustomScript.forceOnTop = 1
  }
  

• 如果确实需要大规模调整原扩展的静态资源，再复制整份文件到自己扩展里，通过TypoScript替换掉原扩展的资源引入路径。

TypoScript配置 #

• 不要修改原扩展的TypoScript文件，在自己sitepackage的Configuration/TypoScript/目录下新建setup.typoscript和constants.typoscript。
• 进入后台模板模块，在页面根模板的“包含静态模板”列表里，把你自己sitepackage的模板加进去，位置放在bootstrap_package、Pizpalue模板的后面。
• 所有需要修改的原扩展配置，直接在自己的setup文件里重写对应配置项即可，不需要复制整份原配置。

ext_tables.sql数据库修改 #

• 把你需要新增、调整的数据库字段定义，直接写到自己sitepackage根目录下的ext_tables.sql里即可，不要动原扩展的sql文件。
• 写完后在后台运行数据库分析工具，或者CLI执行vendor/bin/typo3 database:updateschema完成数据库结构更新，你自定义的字段会永久保留，原扩展更新不会改动这部分内容。

注意：不要直接修改原扩展已经定义的核心字段结构，避免版本更新时出现字段冲突，新增字段建议加自定义前缀做区分。

PHP代码修改 #

• 优先用TYPO3原生的事件监听、钩子机制实现逻辑修改，兼容性最好，大版本升级不容易报错。
• 如果没有对应事件/钩子可以用，再通过XCLASS机制覆写原类：自己写的PHP类放到sitepackage的Classes/目录下，按PSR-4规范写命名空间，继承你要修改的原扩展类，只重写需要调整的方法即可。最后在sitepackage根目录的ext_localconf.php里注册XCLASS映射：

  $GLOBALS['TYPO3_CONF_VARS']['SYS']['Objects'][\BK2K\BootstrapPackage\DataProcessing\ContentElementProcessor::class] = [
      'className' => \MyVendor\MySitepackage\DataProcessing\CustomContentElementProcessor::class
  ];
  

• 新增自定义的PHP类、数据处理器、钩子逻辑，直接放到sitepackage的Classes/目录下按规范注册即可。

第三步：后续更新注意事项 #

• 所有修改都收敛到自己的sitepackage里之后，后续更新bootstrap_package、Pizpalue时，只需要更新完成后清理系统缓存，检查下原扩展有没有大版本的类名、模板路径变动即可，你所有的自定义代码、新增文件都不会被覆盖。
• 日常维护时绝对不要在第三方扩展的目录下做任何文件修改，避免出现意外的内容丢失。

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