Composer中文镜像为国内PHP开发者刚需，配置需严格遵循键名repo.packagist、type值composer、HTTPS带尾斜杠URL；全局配置易失效，推荐项目级配置并删除vendor与composer.lock后重装。
Composer中文镜像不是“锦上添花”，而是国内PHP开发者绕不开的刚需——不配，composer install就大概率卡在 Loading composer repositories，超时、重试、失败反复循环。
composer config -g repo.packagist 为什么总不生效
这不是网络问题，是命令写错了三个硬性条件中的至少一个：
-
repo.packagist键名不能多写一个s（repos.packagist❌），也不能少写repo.（packagist❌） -
composer是必须显式写出的type值，漏掉它会静默 fallback 到官方源 - URL 必须是 HTTPS，且末尾带斜杠：
https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（404）
验证是否成功：直接运行 composer config -g repo.packagist。输出必须是完整 JSON 对象，比如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、只返回 URL 字符串，都说明没写对。
项目级配置比全局配置更可靠
宝塔后台用 www 用户跑命令，CI 流水线用 runner 用户，Docker 构建里甚至没有 ~/.composer 目录——这些场景下，composer config -g 配的全是“空气”。
立即学习“PHP免费学习笔记（深入）”；
进项目根目录，执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
这条命令会自动往 composer.json 的 repositories 字段安全追加，不覆盖已有私有源。但注意：
- 如果
composer.json里原先是"repositories": []（数组），命令会报错；得先手动改成"repositories": {}（空对象）再运行 - 千万别手写
"packagist.org": false—— 这会彻底关掉基础包校验，连php或ext-json都装不上 - 改完立刻删掉
vendor和composer.lock，再跑composer install，否则旧 lock 文件里的 hash 可能和镜像元数据不匹配
临时换镜像只对当次命令有效
不想动任何配置，又想验证某个镜像是否可用？加 --repository-url 参数：
composer install --repository-url=https://mirrors.aliyun.com/composer/
它优先级最高，会覆盖全局和项目级配置。但注意：
-
composer require后面加这个参数不生效，只对install和update有效 - 如果命令卡在
Resolving dependencies，和镜像无关——那是依赖解析慢，得检查composer.json写法或本地环境 - 腾讯云、华为云镜像也能用，但阿里云目前同步频率高、稳定性好，出问题概率最低
最常被忽略的一点：换源后第一次 composer install 报 hash 校验失败，很多人会反复重试或怀疑镜像有问题，其实只要删掉 vendor 和 composer.lock 就行——旧 lock 文件记录的是官方源的元数据，和镜像站不一致是必然的。
