composer中文镜像配置不生效的明确原因是键名必须为单数repo.packagist、type值必须显式写composer、url必须以/结尾，三者缺一即静默回退官方源；验证需输出完整json对象。
composer config -g repo.packagist 命令不生效？检查这三个硬性条件
命令执行没报错，但 composer install 日志里还是出现 GET https://packagist.org/ ——这不是网络问题，是配置根本没写进去。Composer 2.0+ 对键名、type 值和 URL 格式做严格校验，缺一即静默 fallback 到官方源。
-
repo.packagist必须是单数，写成repos.packagist或packagist.org都无效 - 中间的
composer是type值，不是注释或可选项，漏掉就等于没配 - URL 必须是 HTTPS 且末尾带
/，例如https://mirrors.aliyun.com/composer/✅，少斜杠会拼出/composerpackages.json导致 404
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON，如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null 或提示 Key does not exist，说明没写进去，立刻重试。
项目级镜像配置为什么优先推荐？
全局配置只在你当前 shell 用户下生效，CI/CD（如 GitHub Actions）、宝塔面板（www 用户）、Docker 容器里根本读不到你的 ~/.composer/config.json。项目级配置写进 composer.json，所有协作者和自动化环境行为一致。
- 进项目根目录，运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g） - 该命令会自动在
composer.json顶层写入"repositories"字段，key 固定为"packagist" - 如果已有
"repositories": []（数组），命令会失败；需先手动改为"repositories": {}（空对象）再重试 - 哪怕只写
"repositories": {}，也会禁用默认源——这是 Composer 设计逻辑，不是 bug
换镜像后 composer install 报 hash 不匹配？删 lock 和 vendor
这不是网络超时或权限问题，是旧 composer.lock 文件里记录的包哈希和 dist URL 来自官方源，切换镜像后 Composer 仍按原路径去阿里云找 zip 包，但镜像服务的内部路径映射与 packagist.org 不同，校验必然失败。
- 删掉项目下的
vendor/目录 - 删掉
composer.lock文件 - 再执行
composer install（不是update），让 Composer 重新解析依赖、生成适配新镜像的 lock 文件
顺手加个 -vvv 观察日志，确认请求地址已变成 mirrors.aliyun.com，而不是 packagist.org。
卡在 Resolving dependencies？镜像帮不上忙
镜像只加速元数据和 ZIP 包下载，不参与依赖解析。如果你发现 composer update 卡在 Resolving dependencies 几十秒甚至几分钟，问题一定出在本地约束或 composer.json 写法上。
-
"php": "^7.4 || ^8.0"这类宽泛版本约束会让 Composer 尝试大量组合 -
require-dev里塞了太多未锁定版本的工具链，比如"phpunit/phpunit": "^10.0" - 用了大量
dev-main或dev-develop分支依赖
这类问题换任何镜像都无效，得收紧版本约束、锁定 minor 版本、精简 require-dev。别在镜像上浪费排查时间。
