最常见原因是Composer全局二进制路径未加入$PATH，且Composer 2.2+默认拦截插件需显式配置allow-plugins。
全局插件命令“装了却用不了”怎么定位
最常见原因是 ~/.composer/vendor/bin（Linux/macOS）或 %APPDATA%\Composer\vendor\bin（Windows）没进 $PATH。运行 composer global require laravel/installer 后，二进制文件确实落进去了，但 shell 根本找不到它。
先确认路径：composer config --global home 输出后拼上 /vendor/bin 就是真实位置；再检查 $PATH 是否包含该路径。没加就补：
- Linux/macOS：在
~/.zshrc或~/.bashrc末尾加export PATH="$HOME/.composer/vendor/bin:$PATH"，然后source ~/.zshrc - Windows：系统属性 → 环境变量 → 用户变量里新增
%APPDATA%\Composer\vendor\bin
别信 which laravel 或 where laravel —— 它们查的是当前 PATH，不是插件安装位置。
插件装上了但报 “command not found” 或静默失效
Composer 2.2+ 默认拦截所有插件，allow-plugins 是硬开关，不是可选项。即使你 global require 成功，没配这个，插件的命令根本不会注册进 CLI。
必须显式声明允许范围：
- 项目级生效：在项目根目录
composer.json中加"allow-plugins": ["laravel/installer"]，大小写敏感，不支持通配符 - 全局插件想跨项目用？不行。Composer 不支持全局级
allow-plugins，每个项目都得单独配 - 如果插件名含 vendor，比如
phpunit/phpunit，必须写全："allow-plugins": ["phpunit/phpunit"]
改完记得 composer install 或 composer update --lock 让配置落地，否则不生效。
插件校验失败：checksum verification failed 怎么破
启用阿里云、腾讯云等中文镜像时出现 checksum verification failed 或 Signature verification failed，切回官方源就正常——这不是插件本身问题，而是镜像同步延迟导致 dist.sha256 或签名元数据与 composer.lock 里存的旧值对不上。
只删 vendor 或只清缓存没用，因为 composer.lock 还锁着旧哈希：
- 先彻底清理：
rm -rf vendor composer.lock（Windows 用rd /s /q vendor & del composer.lock） - 临时禁用镜像：
composer config -g --unset repos.packagist，再切回官方源：composer config -g repo.packagist composer https://packagist.org - 重装：
composer install，此时会拉取最新元数据，生成带正确哈希的新composer.lock - 验证无误后再决定是否换镜像——建议等 30 分钟，或优先试华为云镜像（同步更稳）
PHP 版本或扩展缺失导致插件启动报错
很多插件（如 laravel/installer、phpunit/phpunit）依赖特定 PHP 扩展或版本约束。报错像 Class 'Phar' not found 或 require php ^8.1 不满足，说明 CLI 环境和 Web 不一致。
别只看 phpinfo() 页面，要查 CLI 真实状态：
- 运行
php -v确认 PHP CLI 版本 - 运行
php -m | grep -E "phar|openssl|mbstring|json|curl"，缺哪个就装哪个（Ubuntu 上是sudo apt install php-phar php-openssl php-mbstring） - 某些插件要求
phar.readonly=Off，检查php --ini加载的 php.ini，把这行设为Off
插件本身不报详细依赖错误，往往卡在 autoload 阶段，所以第一步永远是验证 PHP CLI 环境干净可用。
