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 配置。
