composer 不支持 bin-compat=full_composer,仅接受 full 或 symlink;跨平台兼容依赖 bin-dir、bin-compat=full 及 windows 下自动生成 .bat 文件协同实现。

直接说结论:Composer 本身不提供 bin-compat=full_composer 这种配置项,这是对 bin-compat 机制的常见误解。它只支持 full 或 symlink 两种值,而所谓“跨平台 bin 脚本兼容”,实际靠的是 bin-dir + bin-compat + Windows 下的 .bat 自动生成三者协同工作。
为什么 bin-compat=full_composer 会报错或无效
Composer 的 bin-compat 配置仅接受字符串 "full" 或 "symlink"(默认为 "symlink"),源码里没有 full_composer 这个枚举值。如果你在 composer.json 或 config.json 里写了这个值,Composer 会静默忽略,或者在较新版本中报 Invalid value for bin-compat 错误。
-
full:为每个 bin 脚本生成独立的可执行文件(Linux/macOS 是 shell 脚本,Windows 是.bat) -
symlink:只在 Linux/macOS 生效,Windows 下自动 fallback 到full(但不会生成额外的“Composer 特供”脚本) - 不存在
full_composer—— 它不是 Composer 的选项,也不是社区约定俗成的别名
怎么让 vendor/bin/xxx 在 Windows 和 Linux/macOS 上都可执行
关键不是改一个不存在的配置,而是确保三件事同时到位:Composer 版本 ≥ 2.2、bin-compat 设为 full、且项目依赖的 bin 脚本本身是标准 PHP CLI 入口(即有 #!/usr/bin/env php 或等效逻辑)。
- 在项目级
composer.json中加:"config": { "bin-compat": "full", "bin-dir": "bin" } - 或全局设置(影响所有项目):
composer config -g bin-compat full - 运行
composer install或composer update后,检查bin/目录:Linux/macOS 下看到无扩展名脚本,Windows 下会多出xxx.bat - 注意:如果依赖包的
bin指向的是 Phar 文件(如phpunit.phar),Composer 不会重写它,也不会生成 .bat —— 此时需手动 wrapper 或用php xxx.phar显式调用
容易踩的坑:Windows 下 vendor/bin/xxx 仍报“不是内部或外部命令”
这不是 bin-compat 没生效,而是 Windows 执行环境没识别到 .bat 文件,或路径未加入 PATH。
- 确认你执行的是
vendor\bin\xxx.bat(而不是vendor\bin\xxx),后者在 Windows 命令行里不可执行 - 如果用 Git Bash / WSL,它默认不认
.bat,此时应设bin-compat=symlink并在 WSL 里用vendor/bin/xxx(Linux 模式) -
bin-dir路径含空格或中文?会导致.bat脚本生成失败,出现语法错误(比如was unexpected at this time) - 某些 IDE(如 PhpStorm)终端未刷新 PATH,重启终端或手动运行
refreshenv(Windows)
真正决定跨平台 bin 可用性的,是 bin-compat=full 触发的 .bat 生成逻辑 + 当前 shell 环境能否匹配该格式。别被名字误导——没有“full_composer”这种中间态,只有 full 或 symlink,而 Windows 下的兼容性,本质上是靠 .bat 文件兜底,不是靠 Composer “翻译”脚本。










