根本原因是composer_home路径错误或vendor/bin未加入path；需确认composer_home为绝对路径、将对应vendor/bin添加至系统path并重启终端，再验证composer config --list --global输出是否匹配。
Windows 下 COMPOSER_HOME 路径写错会导致全局命令失效
很多人执行 composer global require laravel/installer 成功，却在终端敲 laravel 报“不是内部或外部命令”，根本原因不是 Composer 没装好，而是 COMPOSER_HOME 被错误覆盖，或者 PATH 没指向它的 vendor/bin 目录。
关键点：Composer 默认把全局可执行文件放在 %APPDATA%\Composer\vendor\bin（Windows）或 ~/.composer/vendor/bin（Linux/macOS）。如果你设了 COMPOSER_HOME，它就完全接管这个路径——但必须是绝对路径，不能含 %USERPROFILE%、~ 或任何环境变量占位符。
- 设完
COMPOSER_HOME后必须重启终端，否则 shell 仍读旧值 - 验证是否生效：运行
composer config --list --global，看顶部 “Global configuration file” 路径是否与你预期一致 - Windows 用户注意区分“系统变量”和“用户变量”，推荐设为系统变量，避免不同账户行为不一致
PATH 必须显式包含 vendor/bin 才能运行全局命令
composer global require 只负责把二进制文件放进 vendor/bin，它不会自动加进系统 PATH。这是最常被忽略的一环。
操作步骤：
- Windows：把
%APPDATA%\Composer\vendor\bin（或你自定义的COMPOSER_HOME\vendor\bin）添加到系统环境变量Path中 - Linux/macOS：在
~/.zshrc或~/.bashrc末尾加一行：export PATH="$HOME/.composer/vendor/bin:$PATH" - 改完后新开终端，再执行
echo %PATH%（Windows）或echo $PATH（macOS/Linux）确认路径已生效
全局镜像配置要走 config -g，别在项目里乱设
国内访问 Packagist 慢，换阿里云镜像是刚需。但镜像地址必须用全局配置，否则每次进新项目都要重复设置，且容易和项目级配置冲突。
正确命令只有一条：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
这条命令会直接修改全局配置文件（通常是 %APPDATA%\Composer\config.json 或 ~/.composer/config.json），后续所有 composer install、require 都自动走镜像。
- 别用
composer config repo.packagist ...（缺-g），那只是当前目录下的项目级配置，毫无意义 - 如果之前误配过，先用
composer config --list --global查看，再用composer config --global --unset repo.packagist清除 - code-server 等 Web IDE 共享系统环境，全局配置一次即可，无需额外处理
composer install --no-dev 不是默认行为，部署时漏掉就翻车
很多人以为 require-dev 的包只在本地存在，其实只要没加 --no-dev，composer install 就会照单全收——包括 phpunit、laravel/pint 这类纯开发工具。线上环境混入它们，轻则体积膨胀，重则因类加载冲突导致 Class not found。
CI/CD 和生产部署中务必显式带上：
-
composer install --no-dev --prefer-dist：跳过require-dev，优先用压缩包提速 - Dockerfile 里漏写
--no-dev是高频事故点，尤其当composer.lock里记录了 dev 包时 - GitHub Actions 等 CI 工具若复用缓存，缓存键必须包含
--no-dev标志，否则可能复用上一轮带 dev 的vendor/
真正需要“多环境依赖”的场景，靠 require-dev 切分是徒劳的——Composer 没有环境感知能力，得靠外部机制驱动，比如 COMPOSER=composer.prod.json composer install。
