全局镜像配置常因用户上下文错位、拼写错误、URL缺斜杠或配置残留而静默失效；项目级配置更可靠，需清空vendor和composer.lock后重装。
直接执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 就能生效，但 90% 的失败不是网络问题，而是命令写错、用户上下文错位或配置残留导致的静默失效。
全局镜像配置为什么经常不生效？
因为 composer config -g 写入的是当前执行用户的 ~/.composer/config.json，而真正跑命令的可能是另一个用户：
- 你在终端用
root执行了配置，但宝塔后台以www用户运行composer install，它读不到root的配置 - CI 脚本里用了
sudo composer config -g，结果写进了root配置，而 runner 容器里是普通用户 - 拼写错误如
repos.packagist（多一个 s）或漏掉composertype 值，命令不报错但实际没写入任何有效字段 - URL 少了末尾斜杠：
https://mirrors.aliyun.com/composer→ 会拼成 404 地址
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON 对象（如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}），空、null 或仍显示 https://packagist.org 都说明没生效。
项目级配置才是团队协作的可靠方案
进项目根目录后执行这条命令：
立即学习“PHP免费学习笔记（深入）”；
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
它会自动在 composer.json 顶层添加或合并 "repositories" 字段，不覆盖已有私有源。优势很明显：
- 配置随代码提交，新人
git clone && composer install即可开干 - CI 构建时自动读取，无需额外
composer config -g步骤 - 避免不同项目因全局配置冲突导致依赖解析不一致
注意：如果项目已有 "repositories": {}（空对象），命令能安全 merge；如果是 "repositories": []（空数组），命令会报错，需先手动改成对象格式。别手写 "packagist": false，这会彻底关掉基础包源。
换源后还卡在 Resolving dependencies？那和镜像无关
镜像只加速「下载」阶段，不解决「依赖解析」慢的问题。常见真实瓶颈：
-
PHP内存不足：默认128M不够，临时加COMPOSER_MEMORY_LIMIT=-1再试 -
Xdebug启用中：会让解析慢 5–10 倍，用php -d xdebug.mode=off $(which composer) install临时禁用 -
platform配置与实际PHP版本不匹配：比如"php": "7.4"却在PHP 8.5.5上运行，触发降级查找逻辑 -
composer.lock旧文件残留：换源后首次composer install若报 hash 校验失败，必须删掉vendor/和composer.lock重来
临时验证镜像可用性，别动任何配置
只想快速测试某个镜像是否通，用 --repository-url 参数：
composer install --repository-url=https://mirrors.aliyun.com/composer/
它优先级最高，会覆盖全局和项目配置，且只影响当次命令。适合 CI 脚本或排查网络问题。但注意：
- 这个参数对
composer require无效，必须配合install或update - 如果同时用了
composer.json里的repositories，它依然会被覆盖 - 地址必须是 HTTPS，且末尾带斜杠，否则卡在
Loading composer repositories几十秒后报Could not fetch ... packages.json
最常被忽略的一点：换源只是第一步，后续所有操作都得基于干净的 vendor/ 和 composer.lock ——哪怕只改了一行配置，也要清掉这两个再重装，否则 hash 不匹配、包版本错乱、甚至 PHP 8.5.5 下出现不可预知的 autoload 错误。
