composer国内镜像配置必须同时满足三个硬性条件才生效：键名严格为repo.packagist（单数、小写）、type值显式写composer、url以https://开头且末尾带/，任一缺失即静默回退官方源。
国内用 Composer 不配镜像，基本等于没法装依赖——不是慢，是大概率失败。超时、403、卡在 Downloading...，根源全在直连 packagist.org。配镜像不是“提速技巧”，而是能跑起来的前提。
composer config -g repo.packagist 命令为什么总不生效
它不报错，但完全不走镜像，90% 是因为三个硬性条件漏掉一个：
-
repo.packagist不能写成repos.packagist（多一个s就静默忽略） - 第二个参数必须显式写
composer（这是仓库类型声明，漏掉就 fallback 到官方源） -
URL必须是https://开头，且末尾带/：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌
验证是否写入成功：运行 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 字段追加条目，但前提是：repositories 已存在且为对象或数组格式。
- 如果
composer.json原本是"repositories": {}，命令会转为标准数组并插入 packagist 条目 - 如果原本是
"repositories": [ ... ]，命令会向数组末尾追加新项，不破坏已有 Git/VCS 源 - 千万别手动写
"packagist": false—— 这会导致基础扩展（如ext-json）校验失败 - 改完后建议运行
composer update --lock，确保composer.lock记录新源地址
宝塔、CI 或 Docker 里镜像为啥还是不生效
全局配置 composer config -g 写的是当前用户的 ~/.composer/config.json，而宝塔默认以 www 用户运行，CI 流水线用 runner 或 git 用户，Docker 容器里可能是 www-data 或自定义用户——它们都读不到你本地 root 或个人账户下的配置。
- 排查方法：在对应环境里先切到实际执行用户（如
sudo -u www whoami），再运行composer config -g repo.packagist - 给
www用户配镜像：sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI 脚本中别依赖全局配置，改用临时参数：
composer install -vvv --repository-url=https://mirrors.aliyun.com/composer/ - Dockerfile 中若用
USER www-data，则composer config -g必须在该用户上下文中执行
换镜像后 install 报 hash 不匹配或 package not found 怎么办
镜像只加速下载，不改变包内容；但元数据同步可能有延迟或缓存残留，旧 composer.lock 记录的是官方源的哈希值，和镜像返回的元数据不兼容。
- 首次换源后出现
hash does not match或package is not installed，直接删掉vendor/和composer.lock - 再执行
composer install，让 Composer 重新从镜像拉取元数据并生成新 lock 文件 - 顺手清下缓存：
composer clear-cache，避免旧 ZIP 包干扰 - 如果仍卡在
Resolving dependencies，和镜像无关——检查是否启用了xdebug、minimum-stability设为dev、或 PHP 版本约束太宽（如"php": ">=7.4"）
最易被忽略的一点：换镜像只是第一步，真正影响速度的还有缓存路径是否落在 SSD 上、xdebug.mode 是否关闭、以及 composer.lock 是否被正确提交和复用——这些环节任何一个出问题，镜像带来的收益都会打折扣。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
