如何自定义Composer的安装目录结构

如何自定义Composer的安装目录结构

config.vendor-dir 是唯一真正生效的全局路径配置

如果你想把整个项目的依赖安装目录挪个地方，那么请记住：真正全局生效且被所有Composer命令（install、update、require）一致认账的，有且只有 config.vendor-dir 这一个配置项。它必须写在项目根目录的 composer.json 文件里，而且有个关键前提——它只在目标 vendor 目录还不存在的时候才会起作用。

这里有个非常典型的“坑”：很多人先运行了 composer install，生成了默认的 vendor 目录，然后才想起来去补这个配置。结果就是，旧的 vendor 安然不动，Composer 既不会帮你迁移它，也不会把新安装的包写到新路径去。

• 路径怎么写？ 必须是相对路径，比如 "third-party" ✅。绝对路径（如 "/var/www/myapp/third-party"）或者以根目录开头的路径（"/third-party"）都是无效的 ❌。
• 操作顺序是什么？ 配置改完后，必须手动删除现有的 vendor 目录，然后再执行 composer install（注意，不是 dump-autoload）。
• composer.lock 怎么办？ 通常可以保留。但如果你想彻底重置，从头开始，那么建议把 composer.lock 也一并删除。

extra.installer-paths 只对特定 type 的包生效

千万别误会，extra.installer-paths 可不是用来“自定义所有包安装位置”的万能钥匙。它实际上是 composer/installers 这个插件提供的能力，只对那些明确声明了特定 type 的包（比如 wordpress-plugin、drupal-module）才起作用。对于绝大多数普通的 PHP 库（例如 monolog/monolog），这个配置完全无效。

换句话说，如果你压根没安装 composer/installers 插件，这个配置就会被直接忽略。就算装了插件，但目标包没有声明对应的 type，配置同样形同虚设。

• 前提条件： 必须先执行 composer require composer/installers 安装插件。
• 路径规则： 路径值同样是相对于项目根目录的，不支持以 / 开头。例如："wp-content/plugins/{$name}/" ✅。
• 匹配逻辑： 规则按顺序匹配，只取第一个命中的项，不会叠加或合并。
• 生效时机： 已经安装好的包不会被自动迁移。你需要删除 vendor 目录后重新安装，新配置才会生效。

-d 参数和 COMPOSER_VENDOR_DIR 环境变量都靠不住

先说 composer -d /path install 这个命令。它的作用仅仅是告诉 Composer 去哪个路径下寻找 composer.json 和 composer.lock 文件，它完全不会改变 vendor 目录的写入位置。很多人误以为用这个参数就能“换个地方安装依赖”，结果本地测试通过，一到 CI 环境就报 Class not found——因为 vendor 其实还在原项目目录下，而你的脚本却在别处寻找自动加载文件。

再看 COMPOSER_VENDOR_DIR 这个环境变量。它的优先级低于项目内的 config.vendor-dir 配置。也就是说，只有在项目的 composer.json 里没有声明 config.vendor-dir 时，它才会生效。此外，在 Docker、Git Bash 等复杂环境下，它的行为可能不太稳定，依赖它有点像是在走钢丝。

• CI/CD 陷阱： 在 CI 脚本里使用了 -d 参数，却没有同步配置好项目的 config.vendor-dir，几乎百分百会出问题。
• Windows 注意事项： 设置环境变量时要用 set COMPOSER_VENDOR_DIR=lib\vendor，注意反斜杠可能需要转义。
• 全局 vs 项目： 全局性的配置（如环境变量）通常不如项目级配置可靠，尤其是在多个项目共存的开发环境中。

改路径后最常漏掉的三件事

说实话，真正困难的往往不是修改配置本身，而是让整个开发链路都跟上新的路径。稍有遗漏，你就会面临类找不到、命令行工具调不动、IDE 到处报红等一系列头疼的问题。

• 更新自动加载路径： 代码里所有 require 'vendor/autoload.php' 的地方，都必须改成新路径，例如 require 'third-party/autoload.php'。
• 更新二进制工具调用： 所有硬编码调用 Composer 二进制工具的地方（比如 vendor/bin/phpunit），都要同步更新为 third-party/bin/phpunit，并确保你的系统 PATH 或 CI 脚本已经适配了新路径。
• 配置你的 IDE： 像 PHPStorm 这类 IDE，默认只会索引名为 vendor 的目录。你需要在 Settings → PHP → Include Paths 中手动添加新的依赖目录。

这些绝不是可做可不做的“优化步骤”，而是修改路径后必须同步完成的动作。否则，你面对的将不是“路径没改成功”，而是更令人困惑的“看起来改了，但处处都在报错”。