Composer如何设置extra自定义字段_Composer extra扩展配置用法【详解】-composer-PHP中文网

extra字段仅为数据容器，不自动生效，须由插件或脚本主动读取；必须位于composer.json顶层，类型为对象，结构自由，但需避免破折号开头键名、勿嵌套scripts，读取时须做存在性与类型校验。

composer如何设置extra自定义字段_composer extra扩展配置用法【详解】

extra 字段本身不生效，它只是个数据容器；你写进去的任何内容，必须由插件、脚本或工具主动读取，否则就躺在 composer.json 里吃灰。

extra 字段写在哪、长什么样

它必须是 composer.json 的顶层字段，类型为对象（JSON object），结构完全自由：

{
  "name": "my/project",
  "type": "project",
  "extra": {
    "app-version": "2.1.0",
    "build-target": "staging",
    "my-plugin-config": {
      "timeout": 30,
      "skip-validation": false
    }
  }
}

注意几点：

extra 不是配置项，config 才控制 Composer 自身行为（比如 process-timeout）
键名别用破折号开头（如 -debug），JSON 解析可能失败；推荐小写字母+下划线，如 app_env
嵌套对象和数组都合法，适合组织复杂参数
不要在 extra 里塞 scripts —— 那是顶层字段，extra.scripts 不会被自动注册

怎么在自定义脚本里安全读取 extra

你在 scripts 里写的命令（比如 post-install-cmd），可以通过 ScriptEvent 拿到根项目的 extra 数据：

use Composer\Script\Event;

public static function postInstall(Event $event)
{
    $composer = $event->getComposer();
    $extra = $composer->getPackage()->getExtra();

    // 安全取值：先判断键是否存在，再校验类型
    $buildTarget = $extra['build-target'] ?? 'production';
    $config = $extra['my-plugin-config'] ?? [];

    if (is_array($config) && isset($config['timeout'])) {
        // 启动清理、生成配置等逻辑
    }
}

常见错误：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

直接写 $extra['my-plugin-config']['timeout'] —— 缺少键时会 Notice 或 Warning
在 require 的包里读取根项目的 extra —— $composer->getPackage() 返回的是当前包（即那个 require 包）的元数据，不是根项目
把 extra 当全局变量用，没做默认值兜底，导致 CI 环境下 composer install 直接 fatal

插件中读取 extra 的正确姿势

如果你开发的是 type: composer-plugin，必须在 activate() 方法里读取，并做好防御性检查：

use Composer\Composer;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;

class MyPlugin implements PluginInterface
{
    public function activate(Composer $composer, IOInterface $io)
    {
        $extra = $composer->getPackage()->getExtra();

        // 推荐：用唯一前缀避免冲突，比如插件名缩写
        $cfg = $extra['myplugin'] ?? [];
        $enabled = $cfg['enable'] ?? false;
        $logLevel = $cfg['log-level'] ?? 'info';

        if ($enabled) {
            $io->write("MyPlugin activated, log level: {$logLevel}");
        }
    }
}

关键点：