composer config -g repo.packagist 总不生效是因为键名必须为单数 repo.packagist、type 值必须显式写 composer、url 必须 https 且末尾带 /，三者缺一即静默回退官方源；验证需输出完整 json 对象。
composer config -g repo.packagist 为什么总不生效
它不报错，但也不走镜像——这是最坑的地方。根本不是网络差，而是命令漏掉一个硬性条件就静默 fallback 到 https://packagist.org。
-
repo.packagist键名必须是单数，写成repos.packagist或repositories.packagist都无效 - 中间那个
composer是type值，不是可选参数：正确写法是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - URL 必须是 HTTPS + 末尾带斜杠：
https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（缺斜杠会导致请求/packages.json时拼出 404）
验证是否成功？只看这一行：composer config -g repo.packagist。输出必须是完整 JSON，比如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、或仍是 https://packagist.org，说明根本没写进去。
项目级配置怎么避免覆盖私有源
全局配置在宝塔、CI、Docker 里大概率读不到——它们跑在 www、runner 等非当前用户下。进项目根目录，用这条命令更可靠：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意不加 -g）
- 如果原
composer.json是"repositories": {}，命令会自动转为数组并追加packagist条目 - 如果已有 Git 私有源（如
"my-vcs": {"type": "vcs", "url": "https://git.example.com/pkg"}），命令会向repositories数组末尾插入，不破坏原有结构 - 若原
repositories是空数组[]，命令会报错；得先手动改成{}再执行 - 改完必须删掉
vendor/和composer.lock，再跑composer install（不是update），否则 lock 文件仍按旧源地址解析
宝塔/CI/Docker 里镜像为啥不起作用
全局配置写在 ~/.composer/config.json，但它是按用户隔离的：你在终端用 root 配了，宝塔「一键部署」默认用 www 用户跑，它根本读不到。
- 宝塔用户：先确认实际执行用户，
sudo -u www whoami；再针对性配：sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI 脚本或 Docker 构建：别依赖全局配置，直接加参数更稳：
composer install --repository-url=https://mirrors.aliyun.com/composer/ - 临时验证某个镜像是否可用，也用这个参数：
composer create-project --repository-url=https://mirrors.aliyun.com/composer/ laravel/laravel
换镜像后还是卡在 Downloading？
镜像只加速包下载（Downloading 阶段），不解决 Resolving dependencies 慢的问题。如果还卡住，优先检查这几件事：
- 删掉
vendor/和composer.lock后再composer install——旧 lock 文件里的 dist URL 和 hash 可能和镜像元数据不匹配 - 运行
composer clear-cache清掉本地缓存，避免残留旧源响应 - 宽泛版本约束（如
"php": "^7.4 || ^8.0"）会让 Composer 尝试大量组合，收紧版本号能显著提速 - CI/首次部署推荐加参数：
composer install --no-dev --no-scripts --no-autoloader --prefer-dist
最关键的细节：哪怕命令敲对了、镜像也写了，只要 composer.lock 没删，就永远走不了新镜像——这点最容易被忽略。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
