必须执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，键名、type值、URL末尾斜杠三者缺一不可，否则静默回退官方源；旧版Composer 1.x需用repos.packagist加JSON字符串，新版2.2+推荐设http-max-concurrent-downloads为8–10。
镜像配置必须一步到位，否则所有优化都白搭
低配云服务器（比如 512MB 内存、1 核 CPU）上 composer install 卡在 Loading composer repositories 或 Downloading，根本不是网速或内存问题，而是默认直连 packagist.org 导致 DNS 解析失败、TLS 握手超时、CDN 路由绕行——物理链路不通，调任何参数都没用。
唯一可靠命令是：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
这个命令漏一个字符就静默失效，常见错误包括：
-
repo.packagist写成repos.packagist（多s）或packagist.org；中间的composer是type值，不能省略、不能替换为composer2或留空 -
https://mirrors.aliyun.com/composer/少了末尾/→ 返回 404 - 没加
-g→ 只改当前目录，换项目/换用户就失效
配完立刻验证：
composer config -g repo.packagist
输出必须是完整 JSON：{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}。空、null、或仍显示 packagist.org，说明根本没写进去。
旧版 Composer 1.x 和新版 2.x 的键名不兼容
旧版 Composer（1.x）根本不识别 repo.packagist，强行执行会静默忽略。必须改用：
composer config -g repos.packagist '{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}'
注意：repos.packagist（带 s）、type 值用双引号包裹、整个 JSON 字符串要加单引号防 shell 解析。
新版 Composer（2.2+）已弃用 parallel-downloads，改用 http-max-concurrent-downloads：
composer config -g http-max-concurrent-downloads 10
推荐值 8–10，别超 15，否则容易触发临时文件冲突：file_put_contents(/tmp/): failed to open stream。
CI/CD 和宝塔等环境里全局配置不生效
全局配置写在 /root/.composer/config.json，但它只对 root 用户生效。宝塔「一键部署」、PHP 管理器、计划任务默认以 www 用户运行，根本读不到 root 的配置。
解决方法很直接：
- 确认实际执行用户（比如
whoami或查日志 UID） - 针对性配置：
sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - GitHub Actions 等 CI 环境默认不读全局配置，需在 workflow 中显式设置
COMPOSER_HOME或改用项目级配置
项目级更稳妥：进项目根目录，运行（不加 -g）：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
这条命令会自动向 composer.json 的 repositories 数组追加 packagist 条目，不覆盖已有私有源。
换镜像后仍卡在 Resolving dependencies 怎么办
镜像只加速下载，不解决依赖解析阶段的卡顿。Resolving dependencies 这个阶段不走网络，但严重受 PHP 环境和依赖结构影响：
-
memory_limit过低（如 128M），导致依赖图解析失败重试 —— 临时加COMPOSER_MEMORY_LIMIT=-1再试 - 启用了
xdebug（运行php -v可确认），会让解析慢 5–10 倍 —— 用php -d xdebug.mode=off $(which composer) install临时禁用 -
platform配置与实际 PHP 版本不匹配（如"php": "7.4"却在 PHP 8.2 上运行），触发降级查找逻辑 -
composer.lock残留已下线包的引用，导致回退搜索 —— 删掉vendor/和composer.lock，再用composer install --no-cache
真正卡住的时候，往往不是镜像没配好，而是你正在用 PHP 8.5.5 跑一个声明了 "php": "^7.4" 的 ThinkPHP 8.1.0 项目，Composer 在后台反复做兼容性回溯 —— 这种问题，换十个镜像也救不了。
