bin-dir 配置必须置于 composer.json 根级 config 对象内，如 {"config": {"bin-dir": "tools"}}；错误嵌套、遗漏 config 或全局配置冲突会导致失效；Windows 下需避免空格和中文；推荐优先通过 PATH 引入 vendor/bin 而非修改 bin-dir。
composer install 时 bin-dir 配置不生效？检查 composer.json 的根级配置
Composer 的可执行脚本（如 vendor/bin/phpunit）默认放在 vendor/bin/，但这个路径由 bin-dir 配置控制——它必须写在 composer.json 的最外层（root level），不能嵌套在 config 以外的位置。
常见错误是把它误写在 extra 或 scripts 下，或者漏掉 config 容器：
{
"config": {
"bin-dir": "tools"
}
}
修改后需重新运行 composer install 或 composer update 才会重建 bin 目录链接。注意：已存在的 vendor/bin 不会自动清理，建议先删掉再重装。
全局 bin-dir 和本地 bin-dir 冲突怎么办？优先级规则要清楚
Composer 会按以下顺序读取 bin-dir 配置，靠后的覆盖靠前的：
- 项目级
composer.json中的config.bin-dir - 用户级
COMPOSER_HOME/config.json（即~/.composer/config.json或%APPDATA%\Composer\config.json） - 系统级
COMPOSER_HOME下的全局配置（极少用）
如果发现改了项目配置却没生效，大概率是用户级配置里也写了 bin-dir。用 composer config --list 查看实际生效值，用 composer config --global --unset config.bin-dir 清除全局设置。
Windows 下 bin 脚本是 .bat 文件，路径含空格或中文会失败
Composer 在 Windows 上为每个 bin 脚本生成两个文件：xxx（无后缀，供 Git Bash / WSL 使用）和 xxx.bat（供 cmd/PowerShell 使用）。后者对路径敏感：
-
bin-dir值含空格（如"my tools"）会导致.bat脚本解析错误 - 路径含中文字符，在旧版 PowerShell 或某些终端中可能触发乱码或找不到命令
- 推荐使用纯英文、无空格、无特殊符号的路径，例如
"bin"、"scripts"、"dev-bin"
若已出错，错误信息通常是：'php' is not recognized as an internal or external command 或类似路径拼接失败提示。
不想改 bin-dir，但想让终端直接运行 vendor/bin 下的命令？加到 PATH 更实用
多数人真正需求不是移动 bin 目录，而是避免每次敲完整路径。与其改 bin-dir，不如把当前项目的 vendor/bin 加进 shell 的 PATH：
- Bash/Zsh：在
~/.zshrc或~/.bashrc中加export PATH="./vendor/bin:$PATH"（注意是当前目录，不是绝对路径） - Windows PowerShell：用
$env:PATH = ".\vendor\bin;" + $env:PATH（仅当前会话）
这种方式更灵活，且不破坏 Composer 默认行为；但要注意安全：只在可信项目中启用，避免执行恶意包的 bin 脚本。
真正要改 bin-dir 的场景其实很少——比如 CI 环境强制要求所有可执行文件落在 ./tools/，或团队规范统一入口。其他时候，路径本身不重要，能被正确识别和调用才关键。
