深入解析Composer的vendor-bin插件：如何隔离管理工具的二进制文件？

vendor-bin 是 composer 插件 bamarni/composer-bin-plugin 提供的隔离二进制目录机制，用于解决多版本工具冲突问题；它在 vendor/bin 基础上按需创建独立目录（如 vendor-bin/phpstan），仅纳入指定 dev 包的二进制文件，保持依赖隔离且复用标准 autoloading。

vendor-bin 是什么，为什么不能直接放 vendor/bin？

Composer 默认把所有包的二进制文件（比如 phpunit、psalm、php-cs-fixer）软链到项目根目录的 vendor/bin/。问题在于：多个包可能提供同名命令（如两个不同版本的 phpstan），或你想让 CI 脚本调用特定版本而不污染全局 vendor/bin —— 这时 vendor-bin 插件就用来按需创建隔离的二进制目录。

它不改变 Composer 的安装逻辑，只是在 composer install 或 composer update 后，额外生成一个独立目录（默认 vendor-bin），并把指定包的 bin 文件复制/链接进去，互不干扰。

如何启用并配置 vendor-bin？

先装插件：

composer require --dev bamarni/composer-bin-plugin

它会自动注册为 Composer 插件，无需额外启用。

接着在 composer.json 里加 config.bin-dir 和 extra.bin-compat（可选）：

• config.bin-dir 指定新目录路径，比如 "vendor-bin"（默认值）或 "tools"
• extra.bin-compat 设为 true 可让 windows 下也生成 .bat 包装器（否则只有 unix 可执行文件）
• 真正控制“哪些包进 vendor-bin”的，是 require-dev 中包的 bin 字段是否被显式声明 —— 但更常用的是配合 bin-dir + scripts 钩子手动触发

实际推荐做法是：用 composer bin 子命令管理。例如：

composer bin phpstan require --dev phpstan/phpstan

这条命令会：创建 vendor-bin/phpstan/ 目录，把 phpstan/phpstan 安装进去，并只把它的 phpstan 二进制文件放进该目录 —— 其他包不受影响。

常见错误：命令找不到 or 权限拒绝

典型现象：bash: vendor-bin/phpstan/phpstan: Permission denied 或 command not found。

• linux/macOS 下，vendor-bin/* 里的文件默认没有执行权限 —— 插件不会自动 chmod +x，得自己补：

  chmod +x vendor-bin/phpstan/phpstan

• windows 用户如果没开 extra.bin-compat，会发现 phpstan 文件是无扩展名的脚本，CMD 找不到；必须设 "extra": {"bin-compat": true} 再重装
• 误把包装到 require（非 require-dev）会导致 composer bin xxx require 失败，提示 “package is required in root package” —— vendor-bin 只支持 dev-only 包
• 用了 composer bin xxx exec -- phpstan analyse 却报错，往往是因为当前 shell 没把 vendor-bin/xxx 加入 $PATH，得手动加：

  export PATH="vendor-bin/phpstan:$PATH"

和 composer-scripts / tools 目录方案比有什么区别？

有人用 scripts + 自定义 tools/ 目录手动下载二进制，或用 roave/composer-dev-bundle 等替代方案。但 vendor-bin 的关键差异在两点：

• 它复用 Composer 的依赖解析和 autoloading，比如 phpstan 调用的 phpstan-src 类库，仍走标准 vendor/autoload.php，不会因隔离而断掉反射或插件加载
• 每个 vendor-bin/{tool}/ 是独立 composer.json 环境，能指定不同 PHP 版本约束、平台配置，甚至装冲突的依赖版本（只要不跨 bin 目录调用）
• 但注意：它不解决“工具本身需要全局扩展”问题，比如 phpstan 依赖 ext-intl，仍得宿主 PHP 满足 —— 它只隔离 PHP 代码依赖，不隔离 PHP 运行时

路径权限、跨平台兼容性、与 root composer.json 的耦合度，是实际用起来最容易卡住的地方。别跳过 chmod 和 bin-compat 配置。