Composer全局安装后命令找不到，90%是因为~/.composer/vendor/bin（Linux/macOS）或%APPDATA%\Composer\vendor\bin（Windows）未加入系统PATH；Composer从不自动修改PATH，需手动配置并新开终端验证。
composer global require 后命令找不到？PATH 没加对
全局命令不生效，90% 是因为 ~/.composer/vendor/bin（Linux/macOS）或 %APPDATA%\Composer\vendor\bin（Windows）没进系统 PATH。Composer 本身从不自动修改环境变量。
验证方式：echo $PATH（macOS/Linux）或 echo %PATH%（Windows），看输出里有没有对应路径。
- macOS/Linux：在
~/.zshrc或~/.bashrc末尾加一行export PATH="$HOME/.composer/vendor/bin:$PATH"，然后运行source ~/.zshrc - Windows：系统属性 → 高级 → 环境变量 → 用户变量中找到
PATH→ 编辑 → 新建 → 粘贴完整路径（如C:\Users\YourName\AppData\Roaming\Composer\vendor\bin） - 改完必须新开终端，旧终端的
PATH不会自动刷新
为什么 vendor/bin 下有 phpunit，但 global install 后却没生成？
bin 字段只对被安装的包本身起作用——composer require phpunit/phpunit 会让它的 bin 脚本链接到当前项目的 vendor/bin/；而 composer global require phpunit/phpunit 才会把脚本链接到全局 ~/.composer/vendor/bin/。两者互不影响。
常见误操作：
- 在项目里跑
composer global require xxx—— 没错，但命令只存在于全局，和当前项目无关 - 用
composer require --global xxx—— 这是无效命令，--global不是require的合法选项 - 全局安装后仍试图运行
./vendor/bin/xxx—— 那是项目局部路径，不是全局命令位置
自定义 CLI 工具全局可用的三个硬性条件
缺一不可，少一个都会导致 command not found 或 Permission denied：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
-
composer.json中声明了"bin": ["bin/mytool"]，且该路径下文件真实存在 -
bin/mytool文件开头有#!/usr/bin/env php（不能写死成#!/usr/bin/php），且已执行chmod +x bin/mytool - 全局安装时用了
composer global require your-vendor/mytool，而非composer require
Windows 用户注意：.bat 包装器会忽略 shebang，但 PHP 解释器必须能被系统直接调用（即 php 命令在 PATH 中）。
全局命令依赖 autoload.php 怎么写才不翻车？
全局安装的包，其 bin 脚本加载的是全局 vendor/autoload.php，不是你当前项目的。硬写 require 'vendor/autoload.php' 必然失败。
正确写法只有两种：
- 用相对路径：
require __DIR__ . '/../../vendor/autoload.php';（适用于~/.composer/vendor/your-vendor/mytool/bin/mytool结构） - 靠 Composer 自动注入：
$autoload = __DIR__ . '/../../vendor/autoload.php'; if (file_exists($autoload)) { require $autoload; }，更健壮
别图省事用 getcwd() 或 dirname($_SERVER['SCRIPT_FILENAME']) 推导路径——全局命令可能从任意目录执行，当前工作目录不可靠。
