命令总不生效是因为漏加-g、键名写成repos.packagist或url缺末尾/，三者任一出错均静默回退官方源；验证需输出完整json对象{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。
composer config -g repo.packagist 命令为什么总不生效
90% 的“配了镜像还是走 packagist.org”问题，不是网络或权限，而是命令写错一个字符就静默失效：repo.packagist 不能写成 repos.packagist 或 repositories.packagist；composer 这个 type 值必须显式写出，缺了它 Composer 2.x 会直接 fallback 到官方源；URL 必须是 HTTPS + 末尾带斜杠，https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer ❌（少斜杠会导致路径拼成 /composerpackages.json，返回 404 却不报错）。
怎么验证镜像真正在用
别只信 composer config -g repo.packagist 输出结果——它可能显示 JSON，但实际没被读取。最可靠的方法是加 -vvv 跑一次 composer install，然后 grep 日志里是否出现 mirrors.aliyun.com 或 mirrors.tuna.tsinghua.edu.cn；或者运行 composer diagnose，看 “Repo packagist.org” 行后面是不是你设的地址。如果仍是 https://packagist.org，说明配置根本没加载。
宝塔、Docker、CI 里镜像失效怎么办
这些环境默认不继承你的用户级全局配置：sudo -u www composer config -g repo.packagist 在宝塔里查出来是空的，就说明 www 用户没配；Docker 构建时 root 配的 ~/.composer/config.json 对非 root 用户无效；CI 流水线里更常见的是配置写在错误用户家目录下。解决方案很直接：
- 用对应用户重配，例如宝塔里执行
sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI/CD 中优先改用临时参数：
composer install --repository-url=https://mirrors.aliyun.com/composer/ - 项目根目录写进
composer.json的repositories字段，比全局配置更稳定，拉代码即生效
换镜像后 vendor 安装失败或 hash 不匹配
镜像只加速下载，不改变包内容，但元数据同步有延迟或本地缓存残留。首次切换镜像后，composer install 报 hash does not match 或 package is not installed 是典型症状。这不是镜像问题，而是旧 composer.lock 记录的是 packagist.org 的哈希值，和新镜像返回的元数据不兼容。必须删掉 vendor/ 和 composer.lock，再跑 composer install —— 别试图保留 lock 文件，它已经失效。
最容易被忽略的是：镜像只解决下载环节，卡在 Resolving dependencies 或 Loading composer repositories 超过 30 秒，大概率是 DNS、TLS 握手或 IPv6 fallback 拖慢，跟镜像本身无关。这时候该调 COMPOSER_IPV4=1 或 composer config -g http.timeout 600，而不是反复换源。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
