如何自定义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 中手动添加新的依赖目录。
这些绝不是可做可不做的“优化步骤”，而是修改路径后必须同步完成的动作。否则，你面对的将不是“路径没改成功”，而是更令人困惑的“看起来改了，但处处都在报错”。
