如何在Composer中为私有包设置自定义安装器？ (composer-installers)

composer-installers 是 Composer 插件，用于将私有包按自定义 type 安装到指定路径（如 web/themes/custom/），需在私有包中声明小写连字符格式 type，并在主项目中引入插件及配置 installer-paths。

什么是 composer-installers，它能做什么

composer-installers 是一个 Composer 插件，用于让私有包（或第三方包）按自定义路径安装，而不是默认的 vendor/ 下。它本身不处理鉴权或源配置，只接管安装逻辑——比如把一个叫 my-company/theme-base 的包装进 web/themes/custom/theme-base/，而不是 vendor/my-company/theme-base/。

它依赖包的 type 字段匹配预设规则（如 drupal-module → web/modules/contrib/），也支持自定义 type 映射。

如何为私有包声明自定义 type 并启用安装器

私有包自身必须在 composer.json 中明确声明 type，且该 type 需被 composer-installers 识别或扩展。项目根目录的 composer.json 还需引入插件并配置映射。

• 私有包的 composer.json 必须含 "type": "my-company-plugin"（不能是任意字符串，否则无匹配）
• 主项目的 composer.json 要 require composer-installers：

  "require": {
    "composer-installers": "^2.0"
  }

• 同时在主项目中用 extra.installer-paths 显式指定路径（推荐方式，比改 type 更可控）：

  "extra": {
    "installer-paths": {
      "web/plugins/{$name}/": ["type:my-company-plugin"]
    }
  }

• 注意：{$name} 是占位符，会被实际包名替换；type:xxx 中的 xxx 必须与私有包声明的 type 完全一致

常见错误：type 不生效或路径没变化

最常踩的坑不是写错路径，而是 type 没被识别或未触发插件逻辑：

Calliper 文档对比神器

文档内容对比神器

下载

• 忘记在主项目中 require composer-installers —— 即使私有包写了 type，没插件也不会重定向
• 私有包的 type 值用了空格、大写或特殊字符（如 MyPlugin），而 composer-installers 只接受小写连字符格式（my-plugin）
• 用了 installer-paths 但没加双引号包裹键名（如 web/plugins/{$name}/: 少了引号），导致 JSON 解析失败，Composer 静默忽略该条目
• 运行 composer install 前没删掉 vendor/ 和 composer.lock —— 已安装的包不会自动迁移，必须重新安装才走新规则

替代方案：不用 composer-installers，直接用 scripts + post-autoload-dump

如果只是偶尔需要移动几个私有包，或者 composer-installers 的 type 匹配太僵硬，可以绕过它，用 Composer 原生脚本钩子：

• 在主项目 composer.json 的 scripts 中添加：

  "scripts": {
    "post-autoload-dump": [
      "rm -rf web/my-custom-dir && cp -r vendor/my-company/private-package web/my-custom-dir"
    ]
  }

• 这种方式完全跳过安装器，适合路径逻辑复杂、或需条件判断的场景
• 缺点是破坏了 Composer 的可预测性，且无法被其他工具（如 IDE 或部署脚本）感知安装位置

真正麻烦的不是写配置，而是确保私有包的 type 在发布前就定好、文档写清楚、所有协作方都理解这个约定——一旦改 type，旧版本 lock 文件可能卡住路径逻辑，得手动清理。