Composer命令运行前提为PHP已正确安装且PATH配置生效，全局镜像配置必须严格执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，缺-g、键名错误、漏composer类型或URL末尾无斜杠均会导致静默失效。
必须先确认 PHP 已就位，否则 composer 命令根本跑不起来。 它不是独立程序，而是 PHP 脚本，php -v 报错时，别急着配镜像——先修环境。
composer 命令找不到？PATH 没生效是头号拦路虎
哪怕你用 Composer-Setup.exe 装完了，composer --version 还是报错，大概率是 PATH 没加进去。
- 安装时务必勾选 Add to PATH（新版安装器默认不勾）
- 如果漏了，手动把
C:\ProgramData\ComposerSetup\bin加进系统环境变量Path - 改完 PATH 后，必须新开一个终端再试——已打开的 CMD/PowerShell 不会自动 reload
- 验证方式：运行
echo %PATH%，看输出里有没有那条路径
全局镜像配置命令必须带齐三要素，缺一即静默失效
这条命令不是“大概对就行”，漏掉任意一项都不会报错，但实际不生效：
-
-g不能省——没它就只改当前项目，换目录就失效 -
repo.packagist是唯一合法键名（注意是repo单数，不是repos；也不能写成packagist.org） -
composer是type值，不是可选参数——漏掉会导致 fallback 到官方源 - URL 必须是 HTTPS，且末尾斜杠
/不能少：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌
正确写法（直接复制执行）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
验证是否生效：
composer config -g repo.packagist
应输出类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。若为空、null 或显示 https://packagist.org，说明没写对。
CI/宝塔/计划任务里镜像不生效？用户权限不一致是根源
全局配置写在 %USERPROFILE%\AppData\Roaming\Composer\config.json，但它只对当前 Windows 用户有效。
- 宝塔后台、计划任务常以
www用户运行，根本读不到你的个人配置 - CI 流水线里，
composer config -g和后续composer install必须是同一用户权限下执行 - 更稳妥的做法是项目级配置：进项目根目录，运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g），它会自动写入composer.json的repositories字段，Git 可跟踪，不受用户影响
换了镜像还是卡在 Downloading… 或 Resolving dependencies？镜像不背这个锅
镜像只加速元数据（composer.json 描述）下载，以下环节它完全不参与：
- ZIP 包解压（尤其含大量小文件的包）
- PHP 扩展编译（比如
ext-redis、ext-swoole） -
autoload生成或vendor/autoload.php写入 - 卡在
Resolving dependencies阶段？基本是composer.json写法问题：PHP 版本约束太宽（如"php": "^7.4 || ^8.0"）、require-dev塞了太多未锁定版本的工具链
公司代理或防火墙拦截了 mirrors.aliyun.com？浏览器里打开试试；CI 中速度慢，优先检查缓存和 --prefer-dist 参数。
真正容易被忽略的是：镜像配置只是第一步，后续所有依赖解析、解压、扩展编译、autoload 生成，全在本地发生——这些环节卡顿，换十次镜像都没用。
