extra字段是Composer根级私有配置区，仅被插件/脚本读取，须为顶层对象，键名限小写字母与下划线，PHP中推荐json_decode读取composer.json的['extra']。
extra字段是给插件和脚本用的“私有配置区”
extra 字段本身不被 Composer 核心解析，它纯粹是为第三方插件、自定义脚本或项目内部逻辑预留的键值存储空间。比如 composer/installers 依赖它来识别包类型，hirak/prestissimo（已归档）曾用它控制并发数，你自己的 post-install-cmd 脚本也能读取它做条件判断。
怎么写 extra 字段才不会被忽略或报错
必须放在 composer.json 顶层，且值只能是对象（不能是数组、字符串或布尔值）。常见错误包括：
- 把
extra嵌套在config或scripts下面 —— 它只认顶层 - 写成
"extra": ["key": "value"]（用了数组语法）—— JSON 不支持键值对数组写法 - 键名含空格或特殊字符（如
my plugin config）—— 大多数插件只认下划线/小写字母命名的键
正确示例：
{
"name": "my/project",
"type": "project",
"extra": {
"branch-alias": {
"dev-main": "2.0-dev"
},
"installer-paths": {
"web/wp-content/plugins/{$name}/": ["type:wordpress-plugin"]
},
"my-custom-flag": true,
"build-env": "staging"
}
}
PHP 脚本里怎么安全读取 extra 数据
通过 Composer\InstalledVersions 或直接解析 composer.lock 都不可靠；最稳妥的是在自定义命令中用 Composer\Package\CompletePackageInterface::getExtra() 获取。但更常用、更轻量的方式是：在 scripts 中调用 PHP 脚本时传参，或让脚本读取当前项目的 composer.json 文件。
- 推荐做法：用
json_decode(file_get_contents('composer.json'), true)然后取['extra']—— 简单直接，不依赖 Composer API - 注意：如果脚本在
vendor/bin下执行，路径要用__DIR__.'/../composer.json' - 别用
getenv()或$_SERVER试图“继承” extra —— extra 不会自动注入环境变量
extra 和 config、scripts、autoload 的分工边界
很多人混淆 extra 和其他字段用途：
-
config控制 Composer 自身行为（如process-timeout、fxp-asset相关设置），不是给项目逻辑用的 -
scripts是钩子入口，具体逻辑应写在 PHP 文件里，extra只负责传参 -
autoload影响类加载，和extra无交集；但你可以用extra.autoload-dev-path这类自定义键，让脚本决定是否启用某段 autoload -
extra里的数据不会出现在composer.lock的packages列表里 —— 它只属于根项目
真正容易被忽略的一点：修改 extra 后，composer install 不会触发重安装或重新生成 autoloader，除非你显式运行 composer dump-autoload 或改了 autoload 段。很多调试失败是因为忘了这步。
