composer镜像配置失败的根源在于配置项书写错误、权限不匹配或缓存残留，需严格遵循repo.packagist单数格式、https结尾斜杠、-g全局参数等规则，并通过composer install -vvv验证真实请求地址，配合清缓存、删lock和vendor彻底解决。
composer config -g repo.packagist 输出为空或不是 JSON 对象
说明配置根本没写进去，不是“没生效”，是压根没存成功。Composer 2.x 会静默回退到 https://packagist.org，不报错也不提醒。
-
repo.packagist必须是单数，写成repos.packagist或repositories.packagist.org（2.2+ 才认）都无效 - 命令末尾必须带
composer作为type值：正确写法是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - URL 必须 HTTPS 且以
/结尾：写成https://mirrors.aliyun.com/composer（缺斜杠）会导致拼出/composerpackages.json这种非法路径 - 必须加
-g，否则只改当前项目composer.json，换目录就失效
composer install 卡在 “Downloading” 但日志里没出现镜像域名
说明 Composer 没走你配的镜像，而是 fallback 到了官方源，或者被项目级配置覆盖了。
- 运行
composer install -vvv 2>&1 | head -n 10 | grep Downloading，第一行 URL 才是真实请求地址；只看composer config输出没用 - 检查项目根目录
composer.json是否含"repositories"字段：哪怕只是空数组[]，也会完全屏蔽全局镜像 - 执行
composer config --unset repositories（注意没-g）临时清掉项目级配置 - CI/CD 或宝塔环境常见问题：你用
root配的全局镜像，但实际运行的是www用户，得用sudo -u www composer config -g ...单独配
切镜像后仍报 404、SSL 错误或 JSON decode error
不是网络不通，而是缓存残留、元数据损坏或镜像同步延迟导致 Composer 拿着旧路径去新源上找不存在的东西。
- 先执行
composer clear-cache；Windows 用户还得手动删%LOCALAPPDATA%\Composer\cache - 删掉
vendor/和composer.lock——composer.lock里硬编码了旧 provider 地址，不删它，Composer 就一直重试失败路径 - 手动验证镜像可用性：
curl -I https://mirrors.aliyun.com/composer/packages.json必须返回HTTP/2 200；若返回 HTML 页面（如人机验证），说明该镜像不适合自动化场景 - 某些错误（如
file_put_contents(): Only variables should be passed by reference）其实是镜像返回了乱码或 BOM 头，不是 PHP 语法问题，换阿里云/腾讯云源即可
composer diagnose 报 “Connection to packagist.org failed” 却以为镜像坏了
composer diagnose 根本不读你的镜像配置，它只测 https://packagist.org。这个提示和你配的镜像是否正常毫无关系。
- 真正验证镜像，得用
curl -I直接请求你配的 URL，比如curl -I https://mirrors.aliyun.com/composer/p/monolog/monolog.json - 如果
composer show monolog/monolog找不到包，composer clear-cache不管用——要手动删 provider 缓存目录：rm -rf ~/.composer/cache/repo/https---mirrors.aliyun.com-composer -
Resolving dependencies卡住和镜像无关，那是 SAT 求解器在本地穷举版本组合，用composer update --dry-run --verbose看约束瓶颈
composer install -vvv 的第一行下载地址，再对应删缓存、删 lock、删 vendor，三步做完，基本就通了。
