composer如何配置bin-compat为full_composer确保bin脚本跨平台【执行】

必须手动修改 composer.json 并重装 bin 才能使 bin-compat 生效；设为 “full” 后生成的脚本包含完整 composer 运行时环境，解决 windows 下类加载失败等问题，但需删除 vendor/bin 后执行 composer install 重建。

必须手动改 composer.json 并重装 bin，仅设环境变量或改配置项无效。

什么是 bin-compat 和 full_composer

bin-compat 是 Composer 的一个配置项，控制生成的可执行脚本（比如 vendor/bin/phpunit）如何封装：是用轻量级 shell/bat 包装器（auto），还是直接复制完整 composer 二进制逻辑（full）。设为 full_composer 后，所有 bin 脚本会带上完整的 Composer 运行时环境，才能在 Windows 上正确解析 vendor/autoload.php、处理路径分隔符、兼容 PHAR 内部加载等——这是跨平台执行 PHP CLI 工具（如 phpstan、pest）不出错的前提。

常见错误现象：vendor/bin/psalm 在 Windows 上报 class 'ComposerAutoloadClassLoader' not found，或 linux/macos 下能跑、Windows 下直接报“不是有效的 Win32 应用程序”。

• bin-compat 默认值是 auto，它只生成极简包装器，不带 Composer 自身 bootstrap
• full_composer 不是字符串字面量，而是严格写成 "full"（文档里叫 full 模式，但配置值就是 "full"）
• 这个配置只影响后续 composer install 或 composer update 时新生成的 bin 脚本，已有脚本不会自动更新

怎么配置并生效

不能靠 composer config 命令一次性写入并重装 bin；必须显式编辑 composer.json，再强制重建 vendor/bin。

• 打开项目根目录下的 composer.json，在顶层对象中添加：

  "config": {   "bin-compat": "full" }

• 删掉 vendor/bin 目录（不要只删单个脚本，整目录删）
• 运行 composer install --no-dev 或 composer install（取决于是否需要 dev bin）——关键点：必须重新触发 bin 生成流程
• 检查生成的脚本开头：Linux/macOS 下应含 #!/usr/bin/env php + 大段 Composer bootstrap 代码；Windows 下 .bat 文件应调用 php "%~dp0/../composer.phar" 类逻辑，而非简单 php "%~dp0/../vendor/autoload.php"

为什么 composer config bin-compat full 不起作用

因为 composer config 只写入 composer.json，但不会触发 bin 重生成。更隐蔽的问题是：如果之前已运行过 install，Composer 会跳过 bin 创建步骤，哪怕配置变了——它不感知配置变更对 bin 的影响。

• 执行 composer config bin-compat full 后，composer.json 确实被改了，但 vendor/bin 仍是旧的 auto 版本
• 即使加 --force 或 --reinstall，也不会重建 bin，除非你先删掉整个 vendor/bin
• 某些 CI 环境（如 gitHub Actions）缓存了 vendor，会导致配置改了但 bin 没更新，必须清缓存或加 rm -rf vendor/bin

跨平台执行时真正要检查的三件事

光设 bin-compat 不够，还要确认这三项都对，否则 Windows 上照样挂：

• PHP CLI 版本一致：Windows 和 Linux/macOS 上 php -v 输出主版本号（如 8.2）必须相同，否则 autoload.php 加载可能失败
• vendor/autoload.php 存在且可读：Windows 下注意路径权限和长路径限制（尤其启用 LongPathsEnabled 注册表项）
• 脚本无硬编码路径：比如 #!/usr/bin/env php 在 Windows 的 Git bash 下可用，但在原生 CMD 下会被忽略，此时依赖的是 .bat 文件逻辑——而 full 模式才保证 .bat 正确

最常被忽略的是：改完配置后没删 vendor/bin 就直接跑命令，结果还在用旧脚本。那个 vendor/bin/phpunit 文件本身，就是最终执行载体，它不更新，一切白搭。