使用Composer安装Composer-installer指南

Composer Installer 这个插件，名字听起来像“用于安装 Composer 的工具”，但千万别被名称误导。它的真正作用在于：让第三方包能够按照你项目的框架规范，准确放置到正确的位置。换句话说，当你安装一个 WordPress 插件时，它应该被放到 wp-content/plugins/ 目录，而不是被遗弃在 vendor/ 中。这一切，都由它来负责调度。

然而，很多开发者在兴奋地执行 composer require composer/installers 之后，发现插件并没有按预期工作。问题究竟出在哪里？今天我们就一次性梳理几个最容易踩的坑，帮你彻底搞懂。

你安装了插件，但包没有“搬家”？请先检查包的 type 字段是否正确

这是最常见的错误之一。很多人以为只要本地安装了 composer/installers，所有依赖就会自动被“搬运”到对应的目录。实际上，composer/installers 只是一个“搬运工”，它并不负责判断包应该去哪里，只负责执行搬运指令。而指令的来源，是你要安装的那个包自身声明的 type 字段。

• 一个 WordPress 插件，必须在它的 composer.json 中明确指定 "type": "wordpress-plugin"，搬运工才会将它移动到 wp-content/plugins/ 目录。
• 如果它声明的是 "type": "library"，或者根本没有 type 字段，那么无论你怎么折腾，它都会乖乖待在 vendor/ 中。
• 验证方法很简单：安装完成后，先查看 vendor/ 下是否存在这个包。如果没有，说明它已经被搬走了，再去目标目录（比如 wp-content/plugins/）中查找即可。

因此，不要指望通过修改自己项目的配置来“强制”一个未声明 type 的通用包进入特定目录——它根本不会触发搬运逻辑。

自定义 installer-paths 时，路径变量的写法最容易出错

这个坑也很常见。很多人喜欢在 installer-paths 中玩花样，比如想加入版本号之类的信息。但这里有一个硬性限制：它只支持 {$name} 和 {$vendor} 这两个变量插值，{$version} 是不被识别的。

• 正确的写法："wp-content/plugins/{$name}/": ["type:wordpress-plugin"]
• 错误的写法："wp-content/plugins/{$name}-v{$version}/": [...] —— 这种写法中 {$version} 不会被解析，最终要么生成空目录，要么直接报错。
• 路径结尾的斜杠 / 不能省略，否则在 Windows 下可能因为路径分隔符问题导致创建失败。
• 多个规则写在数组里，顺序不重要，但匹配优先级由 composer/installers 内部实现决定，不建议依赖顺序来控制逻辑。

升级到 Composer 2.5+ 后配置失效？请检查 key 名的拼写

Composer 2.4 起，配置项依然叫 installer-paths（拼写未变），但很多人会误写成 installers-paths 或 install-path。这类拼写错误不会报错，只会被静默忽略——你配了跟没配一样。

• 必须严格使用："installer-paths"（注意是 installer，不是 installers）。
• 完整结构示例：

  {    "extra": {        "installer-paths": {            "wp-content/plugins/{$name}/": ["type:wordpress-plugin"],            "app/Modules/{$name}/": ["type:lara vel-module"]        }    }}

• 验证是否加载成功：运行 composer config extra.installer-paths，输出应为对应的 JSON 对象；若为空，说明 key 写错了，或者没有放在顶层 extra 下。

为什么 vendor/ 里还有包残留？composer dump-autoload 不管用

另一个常见误区：认为 composer dump-autoload 能够重新排列包的位置。实际上，composer/installers 是“安装时”行为，与自动加载完全无关。它只影响 composer install 或 composer update 时的文件落点。

• 残留在 vendor/ 中的包，通常是因为之前没有配置 installer-paths，包已经下载到了那里。新配置完成后，旧包不会自动被搬走。
• 解决方法：手动删除 vendor/xxx/yyy 目录，然后重新执行 composer install 或 composer update xxx/yyy。
• 另外，如果一个包既出现在 installer-paths 规则里，又出现在 require 列表中，它仍然会被复制过去——installer-paths 并不会阻止 vendor/ 下存在副本，只是多建一份软链接或硬拷贝（取决于具体实现）。

总结一下，composer/installers 的核心逻辑非常简单：你配置正确了，包也声明了正确的 type，它才会老老实实工作。否则，一切努力都是白费。记住这一点，以后就不会再为“为什么没生效”而抓狂了。