直接换镜像源不能保证成功，关键在于“换对”：必须用正确命令 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（含 type 值、末尾斜杠），并确保用户权限一致、缓存与 lock 文件清理、repositories 结构兼容，否则配置静默失效。
直接换镜像源能显著提升 PHP 包安装成功率，但关键不是“换”，而是“换对”——90% 的失败不是因为没换，是换得不完整或不生效。
composer config -g repo.packagist 命令为什么总不生效
这条命令极易静默失败，不报错、不提示，但配置根本没写进去。常见原因有三个：
-
repo.packagist写成repos.packagist（多一个 s）：Composer 忽略该字段，查composer config -g repo.packagist返回空 - 漏掉中间的
composer类型值：命令变成composer config -g repo.packagist https://mirrors.aliyun.com/composer/，Composer 2.x 会 fallback 到默认源 - URL 少了末尾斜杠：
https://mirrors.aliyun.com/composer❌ 会导致路径拼接成/composerpackages.json，404 报错但卡在 Loading 阶段不提示
正确写法只有一条：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。验证用 composer config -g repo.packagist，输出必须是完整 JSON 对象，否则重来。
宝塔、CI 或 Docker 里镜像还是慢？用户权限不对
你在终端用 root 配了全局镜像，但宝塔后台部署走的是 www 用户，CI 流水线用的是 runner 用户——它们读的不是同一个 ~/.composer/config.json。
立即学习“PHP免费学习笔记（深入）”；
- 查实际执行用户：在宝塔【终端】里运行
whoami，再执行composer config -g repo.packagist - 若为空，需切用户重配：
sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - Docker 构建时，
-g配置无法持久，建议改用项目级配置或临时参数
项目级配置怎么安全追加不覆盖私有源
进项目根目录后，用 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g），它会自动向 composer.json 的 repositories 字段里追加一条，前提是原 repositories 是对象（如 "repositories": {}）。
- 如果
composer.json里已有"repositories": []（数组），命令会报错；此时需手动编辑，确保新镜像对象排在首位，且保留原有私有源 - 千万别写
"packagist.org": false—— 这会彻底关掉基础包源，镜像一挂就全崩 - 改完必须删掉
vendor/和composer.lock，再跑composer install，否则旧 lock 文件里的哈希和镜像元数据不匹配
换源后仍卡在 “Resolving dependencies”？镜像不背这个锅
这个阶段完全不走网络，纯本地计算。镜像只加速下载，解决不了依赖求解慢的问题。
- 检查
composer.json里是否写了宽泛约束，比如"php": "*"或"monolog/monolog": "dev-main" -
"minimum-stability": "dev"会让 Composer 尝试所有开发分支，求解时间指数增长 - 禁用 Xdebug（
php -d zend_extension=none composer install），它会让依赖解析慢 3–5 倍
真正容易被忽略的点：换源之后，缓存没清、lock 没删、用户没对、type 值漏了——四个环节只要一个断掉，就等于没换。
