不配镜像，composer install 在国内基本跑不通；90% 配置失效因 repo.packagist 拼错、漏写 type 值 composer、url 缺 https 或末尾斜杠；验证须看 composer config -g repo.packagist 输出是否为有效镜像地址，且宝塔/ci/docker 需按实际用户配置，项目级配置需避免覆盖私有源。
不配镜像，composer install 在国内基本跑不通——不是慢，是卡在 Downloading、报 could not find package、或直接 403 Forbidden。镜像不是“锦上添花”，而是 PHP 项目能正常构建的底线。
composer config -g repo.packagist 命令为什么总不生效
90% 的配置失败，根本没报错，但镜像就是不走。问题全卡在这三处：
-
repo.packagist不能写成repos.packagist（多一个s就彻底失效） - 中间那个
composer是type值，必须显式写出；漏掉它，Composer 2.x 会静默 fallback 到https://packagist.org - URL 必须是 HTTPS + 末尾带斜杠：
https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（缺斜杠会导致 404）
验证是否写进去了，只看这一行输出：composer config -g repo.packagist
必须返回完整 JSON 对象（旧版）或纯 URL 字符串（新版）。如果返回空、null、或仍是 https://packagist.org，说明根本没写进去。
宝塔、CI、Docker 里镜像失效的真正原因
全局配置写在 ~/.composer/config.json，但它只对当前用户生效。而宝塔默认用 www 用户执行命令，GitHub Actions 用 runner 用户，Docker 容器里可能是 www-data 或自定义用户——它们都读不到你本地 root 或 yourname 的配置。
- 查实际用户：在宝塔终端运行
whoami，或看计划任务日志里的 UID - 给对应用户配：比如是
www，就运行sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI 脚本里别依赖全局配置，改用临时参数更可靠：
composer install --repository-url=https://mirrors.aliyun.com/composer/
项目级配置怎么避免清空私有源
执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g）时，它**不是追加**，而是全量替换 composer.json 中的 repositories 字段。如果你已有 Git 私有包源，这条命令会把它删光。
- 安全做法：让 Composer 自动合并——前提是
composer.json里repositories是对象格式（如"repositories": {}），不是数组；否则会覆盖 - 已有数组？手动编辑更稳妥：在
"repositories"数组里加一项{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，确保"packagist.org": true（千万别写false） - 改完必须删掉
vendor/和composer.lock，再跑composer install，否则旧锁文件仍指向官方源
配了镜像还是卡在 Resolving dependencies 怎么办
镜像只加速下载环节，Resolving dependencies 卡住和网络无关，是本地解析逻辑出问题：
- PHP 内存不足：在
php.ini中调高memory_limit（至少2G） - 启用了
xdebug：安装依赖前关掉，php -d xdebug.mode=off composer install -
composer.json版本约束太宽：比如用"*"或"^1.0 || ^2.0"，会让 Composer 尝试海量组合 -
config.platform设错：比如声明"php": "8.0"但实际运行在 PHP 8.5，会导致大量包被过滤重算
最直接的判断方式：composer install -vvv 看日志里出现的是 GET https://mirrors.aliyun.com/composer/ 还是 GET https://packagist.org/——前者说明镜像已生效，后者说明配置完全没起作用。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
