配镜像需同时满足键名正确、type值存在、URL格式规范三个条件，否则静默失效；项目级配置须删vendor和composer.lock后执行install，全局配置在宝塔/CI/Docker中需匹配对应用户或使用--repository-url参数。
不配镜像，composer install 卡在 Downloading 或报 403/timeout 是常态，不是你网络差，是默认连 packagist.org 根本扛不住国内链路。配对、配全、配准，才能让依赖安装从“玄学等待”变成确定性操作。
composer config -g repo.packagist 命令为什么总不生效
90% 的失败不是网络问题，而是三个硬性条件漏掉一个就静默失效：
-
repo.packagist不能拼成repos.packagist（多一个s）或repositories.packagist—— 键名错，命令不报错但完全不写入 - 中间那个
composer是 type 值，不是可选参数：正确写法是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，漏掉它，Composer 就 fallback 回官方源 - URL 必须是 HTTPS + 末尾带斜杠：
https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会导致路径拼接错误，返回404后仍 fallback）
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON 对象（如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}）或至少是完整 URL 字符串。空、null、或仍是 https://packagist.org，说明没写进去。
项目级配置怎么避免覆盖私有源且确保生效
进项目根目录后执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g），这条命令会自动向 composer.json 的 repositories 数组追加新项，而不是清空重写：
立即学习“PHP免费学习笔记（深入）”；
- 如果原
composer.json是"repositories": {}，命令会转为标准数组格式并插入 packagist 条目 - 如果原
repositories已有私有 VCS 源（如 Git 地址），命令会向数组末尾追加，不破坏原有结构 - 改完必须删掉
vendor/和composer.lock：因为composer.lock里记录的是旧源下的 dist URL，不删它，composer install仍按旧地址下载，根本不会走新镜像 - 删完只跑
composer install（不是update），让 Composer 从头解析依赖、生成适配新镜像的 lock 文件
宝塔、CI、Docker 里镜像为啥不生效
全局配置（~/.config/composer/config.json）只对当前用户生效。宝塔默认用 www 用户执行命令，CI 流水线用 runner 用户，它们读不到你 root 或个人账户下的配置：
- 宝塔中应切到对应用户配：先确认执行身份（如
sudo -u www whoami），再运行sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI 脚本中别依赖全局配置，改用临时参数更可靠：
composer install --repository-url=https://mirrors.aliyun.com/composer/ - Docker 构建时，若用
root用户构建但容器内以非 root 运行 PHP，也要在 Dockerfile 中指定用户后配镜像，或直接在composer install命令里加--repository-url
换镜像后还是卡在 Resolving dependencies 怎么办
镜像只加速下载环节，Resolving dependencies 卡住和镜像无关，常见真实瓶颈有：
- PHP 内存不足：默认
128M不够，临时加COMPOSER_MEMORY_LIMIT=-1再试 - Xdebug 启用中：会让依赖解析慢 5–10 倍，用
php -d xdebug.mode=off $(which composer) install临时禁用 -
composer.json里版本约束太宽（如"*"或"^1.0"），导致 Composer 遍历大量候选版本 -
config.platform声明的 PHP 版本与实际环境不匹配（如声明"php": "7.4"却在 PHP 8.2 上运行），触发降级查找逻辑
真正容易被忽略的是：改了 composer.json 的 repositories 后，不删 composer.lock 就跑 install，等于白改——lock 文件锁死了旧路径，Composer 完全不重新走镜像解析逻辑。
