composer换源是刚性前提，配错任意字符（如repos.packagist、url缺/、漏-g）即静默回退至packagist.org；必须执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/并验证输出为完整json才生效。
换源不是“试试看”，是 Composer 在国内能跑通的刚性前提；配错任意一个字符，就会静默 fallback 到 packagist.org，所有后续优化都白做。
为什么 composer config -g repo.packagist 总不生效
它根本没写进去——不是命令没运行，而是三个硬性条件漏掉一个就彻底失效：
-
repo.packagist不能写成repos.packagist（多一个s就静默忽略） - URL 必须以
/结尾：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致请求路径拼成/p2//类 404） - 必须带
-g参数，否则只改当前目录下的composer.json，换个项目就回退
验证是否真写入：执行 composer config -g repo.packagist，输出必须是完整 JSON，形如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、报错或只返回 URL 字符串，说明配置失败。
哪些参数真正提升下载成功率（不是速度）
成功率低的本质是弱网下连接中断 + 重试机制太激进，不是带宽问题。以下配置直击失败根因：
- 延长超时：
composer config -g http.timeout 600和composer config -g process-timeout 600（默认 300 秒对国内链路太苛刻） - 增加重试：
composer config -g retries 5（仅 Composer 2.2+ 支持，1.x 版本设了也无效） - 禁用并发干扰：
composer config -g parallel-downloads 1或临时加--no-parallel（某些企业防火墙会拦截并发连接） - 强制 IPv4：
COMPOSER_IPV4=1 composer install（Linux/macOS 可写入~/.bashrc永久生效；IPv6 fallback 卡顿在 DNS 解析后几秒无响应，累加起来就是分钟级等待）
注意：secure-http false 是跳过 SSL 验证，仅限调试，生产环境严禁——它不提速，只降安全水位。
为什么换了镜像还卡在 Downloading 或反复 Could not fetch packages.json
这不是镜像慢，是请求压根没发到镜像站。常见真实原因：
- DNS 缓存未刷新：运行
curl -I https://mirrors.aliyun.com/composer/packages.json，应秒回200；若超时或返回503，先查本地代理或网络设置 - 缓存未清：
composer clear-cache必须紧跟换源之后执行，否则仍在用旧的海外元数据索引 - 用了已停服源：
https://packagist.phpcomposer.com自 2025 年底起不可用，现在返回 404 或空响应，但 Composer 不报错，只重试至超时 - 项目级
repositories覆盖全局：进项目根目录执行composer config --list | grep repositories，确认实际生效的是哪个源；若存在自定义repositories字段，需删掉或显式禁用官方源："packagist.org": false
验证真实请求路径：加 -vvv 运行 composer install，日志里出现 mirrors.aliyun.com 或 mirrors.tuna.tsinghua.edu.cn 才算真走镜像。
Resolving dependencies 卡住？镜像完全不管这事
这个阶段不走网络，纯属本地 PHP 计算。卡住和镜像无关，典型诱因有：
- 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
最容易被忽略的点：宝塔、CI 流水线等环境常以 www 用户运行，但全局配置写在 /root/.composer/config.json，www 根本读不到。必须用 sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 单独配置。
