TYPO3 10+ 必须通过 Composer 安装扩展，将扩展声明在 composer.json 的 require 中并运行 composer require 或 install；官方扩展用 typo3/cms-xxx 命名、自动映射到 sysext，第三方扩展需声明 type: typo3-cms-extension 并依赖 typo3/cms-composer-installers。

TYPO3 10+ 必须用 Composer 安装扩展

从 TYPO3 v10 开始，typo3/cms-core 及所有官方扩展都以 Composer 包形式发布，ext_emconf.php 不再是依赖来源。手动复制扩展文件夹、用 Extension Manager 直接安装 ZIP 的方式在现代项目中已不可靠——它绕过自动加载、不处理 PHP 版本约束、无法复现环境。

你必须把扩展声明在 composer.json 的 require 或 require-dev 中，然后运行 composer install 或 composer require。

安装官方扩展：用 vendor 命名空间 + 版本约束

官方扩展的包名格式统一为 typo3/cms-xxx（如 typo3/cms-fluid、typo3/cms-backend），它们由 typo3/cms-composer-installers 自动映射到 typo3/sysext/xxx 目录，无需手动配置。

Expanso json-flatten

通过 CLI 或 MCP 服务器，使用 Expanso Edge 管道扁平化嵌套 JSON 对象。

下载

• 安装 fluid 和 frontend：运行

  composer require typo3/cms-fluid:^12.4 typo3/cms-frontend:^12.4

• 版本号必须与当前 TYPO3 主版本对齐：^12.4 表示允许 12.4.x，但不允许升到 13.0；错用 ^12.0 可能拉入不兼容的 RC 版本
• 不要写 dev-main 或 dev-master —— 官方不保证开发分支稳定性，且 TYPO3 的 composer/installers 插件默认不处理 dev 分支的 sysext 映射

安装第三方扩展：确认包类型和安装器支持

第三方扩展能否被 Composer 正确安装，取决于它的 composer.json 是否声明了 "type": "typo3-cms-extension"，以及是否依赖 typo3/cms-composer-installers。

• 检查扩展主页或 Packagist 页面，确认其 type 是 typo3-cms-extension（不是 library 或 typo3-cms-plugin）
• 典型命令：

  composer require friendsoftypo3/calendarize:^12.0

  —— 这会把扩展安装到 web/typo3conf/ext/calendarize/（注意路径，不是 vendor/）
• 如果扩展没声明正确 type，Composer 会把它放进 vendor/，但 TYPO3 不会自动加载它；此时需手动加 "extra": {"typo3/cms": {"extension-key": "calendarize"}} 到根 composer.json，并确保 typo3/cms-composer-installers 已启用
• 某些旧扩展仍用 ext_emconf.php 的 constraints 字段声明依赖，Composer 不读这个——你得自己核对 PHP/ TYPO3 版本兼容性

更新时避免“扩展消失”：别跳过 typo3/cms-composer-installers

常见问题：执行 composer update 后，部分扩展在后台 Extension Manager 里不见了。根本原因通常是 typo3/cms-composer-installers 插件未加载，或版本不匹配。

• 确保根 composer.json 中有：

  "require": {
    "typo3/cms-composer-installers": "^4.0"
  }

  （v12 项目用 ^4.0，v11 用 ^3.0）
• 该插件负责把 typo3-cms-extension 类型的包复制到 typo3conf/ext/ 并生成 autoload 配置；缺失它，Composer 就只做普通依赖解析，不触发 TYPO3 特定逻辑
• 升级 TYPO3 主版本时（如 11 → 12），先升级 typo3/cms-composer-installers，再升级 typo3/cms-core，否则 installers 插件可能拒绝处理新版本扩展

扩展管理的核心不在后台界面，而在 composer.json 的声明与 typo3/cms-composer-installers 的执行时机——漏掉任意一环，都会导致扩展存在但 TYPO3 看不见。