composer.json 的 bin 字段需在被安装的包自身中定义，值为字符串或数组（如 "bin": "bin/phpunit"），且对应脚本须有正确 shebang（如 #!/usr/bin/env php）才生效。

composer.json 的 bin 字段怎么写才生效

Composer 本身不自动把包里的可执行文件（如 phpunit、larastan）软链到全局路径，必须靠 bin 字段显式声明。这个字段只在包自身的 composer.json 中定义，不是你项目里配的——也就是说，你装一个包能不能全局调用它的命令，取决于那个包有没有在自己的 composer.json 里写好 "bin"。

常见错误是以为只要包里有 bin/xxx 就能自动识别，其实必须满足两个条件：

• 包的 composer.json 中存在 "bin" 键，值为字符串或字符串数组（如 "bin": "bin/phpunit" 或 "bin": ["bin/phpunit", "bin/phpstan"]）
• 该路径指向的是可执行脚本，且首行有正确的 shebang（如 #!/usr/bin/env php），否则即使软链成功也会报 Permission denied 或直接执行失败

全局 bin 目录在哪？如何确保它在 $PATH 里

Composer 默认把所有包的 bin 文件软链到项目根目录下的 vendor/bin/，这是局部可用的。要全局调用，得用 composer global install，它会把可执行文件统一放到 Composer 的全局 vendor 目录下的 bin/ 子目录中。

这个路径因系统而异：

• Linux/macOS：~/.composer/vendor/bin/
• Windows：%USERPROFILE%\AppData\Roaming\Composer\vendor\bin

但光有路径没用，你得手动把它加进 $PATH：

echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

验证是否生效：echo $PATH 看有没有那段路径；再运行 which phpunit（如果已全局安装 phpunit/phpunit）看是否命中。

composer global require 后命令找不到的典型原因

即使 $PATH 没问题，也常遇到 command not found，核心就三个点：

• 包没声明 bin 字段：比如你 global require friendsofphp/php-cs-fixer，它确实有 bin/php-cs-fixer，且 composer.json 里写了 "bin": ["bin/php-cs-fixer"]，所以能用；但有些小工具包漏写了，那就白装
• 全局安装时用了 --no-bin-links 或配置了 bin-dir 覆盖默认行为（比如在 ~/.composer/config.json 里写了 "bin-dir": "/usr/local/bin"），结果链接被扔到别处甚至没生成
• 权限问题：某些 Linux 发行版（如 Ubuntu）默认禁止从 ~/.composer 执行脚本，需确认 ~/.composer/vendor/bin/ 下的文件有 x 权限（ls -l ~/.composer/vendor/bin/ 查看）

想让自己的包支持全局 bin 调用，composer.json 怎么写

如果你开发一个 CLI 工具包（比如叫 myorg/mycli），想让用户 composer global require myorg/mycli 后就能直接敲 mycli，必须在你包的 composer.json 里明确指定入口：

{
    "name": "myorg/mycli",
    "bin": "bin/mycli",
    "autoload": {
        "psr-4": {
            "MyOrg\\MyCli\\": "src/"
        }
    }
}

同时确保 bin/mycli 是可执行 PHP 脚本：

#!/usr/bin/env php
run();

注意：bin/mycli 必须是 Unix 风格换行（LF），Windows CRLF 会导致 shell 解析失败；而且不能用 .php 后缀（bin/mycli.php 不会被识别）。

真正容易被忽略的是：全局 bin 的生命周期完全依赖 Composer 全局 vendor 目录。一旦你重装系统、清空 ~/.composer、或误删 vendor/bin 下的软链，所有命令就立刻失效——它不像 npm 的 npx 那样按需拉取，也没有缓存兜底。