composer 2.5.0+ 已彻底移除 self-update，必须通过官方脚本重装切换主版本；全局镜像配置需严格使用 repo.packagist 键名、type 值为 composer、https 且末尾带 / 的 url，三者缺一即静默回退官方源。
Composer 2.5.0+ 已彻底移除 self-update，版本切换只能重装；全局镜像配置必须用 repo.packagist 键名、显式 composer type 值、HTTPS 且末尾带 / 的 URL，三者缺一即静默回退官方源。
如何安全切换 Composer 主版本（如从 2.x 升到 3.x）
别碰 self-update —— 它在 2.5.0+ 中已完全删除，执行只会报错 Command "self-update" is not defined。真实切换路径是下载安装脚本重装：
- 下载脚本：
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" - 校验 SHA-384（2026 年最新值）：
php -r "echo hash_file('sha384', 'composer-setup.php');"，比对官网公布的795f976fe0ebd8b75f26a6dd68f78fd3453ce79f32ecb33e7fd087d39bfeb978342fb73ac986cd4f54edd0dc902601dc - 安装到系统路径：
php composer-setup.php --install-dir=/usr/local/bin --filename=composer（Linux/macOS），Windows 请指向C:\ProgramData\ComposerSetup\bin\ - 刷新 shell 缓存：
hash -r（Linux/macOS），Windows 需新开终端
重装后原全局镜像配置不会保留，必须手动重配，否则默认走 https://packagist.org。
为什么 composer config -g repo.packagist 总不生效
不是网络慢，也不是镜像挂了，而是命令本身写错了三个硬性条件，而 Composer 从不报错，只安静 fallback。验证是否真写进去了，唯一依据是运行该命令后输出是否为完整 JSON：
- 键名必须是单数
repo.packagist—— 写成repos.packagist、repositories.packagist.org或大小写混用（如Repo.Packagist）全部无效 - 中间的
composer是必需type值，不是注释或可选项；漏掉它，整条配置被忽略 - URL 必须 HTTPS 且末尾带
/：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会拼出/composerpackages.json导致 404）
正确命令只有一种：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。执行后立刻运行 composer config -g repo.packagist，输出必须是 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 才算成功。
全局配置在 CI、Docker、宝塔里为啥“配了等于没配”
因为全局配置写在 ~/.composer/config.json，它只对「执行命令的用户」生效。你在终端用 root 配的，PHP 进程却跑在 www 用户下，根本读不到那个文件。
- 宝塔：确认实际运行用户（通常是
www），改用sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - Docker：确保
COMPOSER_HOME挂载路径正确（如/home/www/.composer），且构建阶段以目标用户身份执行配置命令 - GitHub Actions：默认用
runner用户，必须在 workflow 中显式运行composer config -g，不能依赖本地配置 - 更稳妥做法：项目级配置 —— 进入项目根目录，运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（无-g），并提交composer.json到 Git
换源后 composer install 还卡在 “Loading composer repositories” 怎么办
这不是镜像没生效，而是 Composer 正在用缓存或 composer.lock 里旧地址反复请求失败。必须清三样：
- 清缓存：
composer clear-cache；Windows 还要手动删%LOCALAPPDATA%\Composer\cache - 删锁文件和依赖：
rm -rf vendor composer.lock（Windows 用rd /s/q vendor && del composer.lock） - 重装并验证真实请求：
composer install -vvv 2>&1 | grep "Downloading"，看第一行 URL 是mirrors.aliyun.com还是packagist.org
如果日志里还是 packagist.org，说明 composer.json 里存在 "repositories" 字段（哪怕只是空数组 []），它会直接屏蔽全局配置。临时禁用：运行 composer config --unset repositories（注意无 -g）。
最常被忽略的一点：换源命令里的 URL 少一个 /，或者 composer.json 里 "repositories" 是数组而非对象，这两处错误都不会报错，但会让整个配置链静默失效——你得靠 -vvv 日志里的域名才能确认真相。
