必须配置国内镜像源，否则ci中composer install因直连packagist.org而卡住或超时；需确保repo.packagist键名准确、type值为composer、url含https及末尾斜杠，并通过项目级配置或清缓存验证生效。
composer install 在 CI 中卡住，不是网络问题，是默认还在直连 packagist.org。不配镜像，构建就大概率失败或超时——这不是优化项，是必须做的前置动作。
为什么 composer config -g repo.packagist 总不生效
这条命令静默失败太常见，根本原因不是权限或网络，而是三个字段必须同时对：
-
repo.packagist是固定键名，写成repos.packagist（多一个 s）或repositories.packagist，Composer 2.x 完全忽略，不报错也不 fallback 提示 - 中间那个
composer是type值，不是可选参数，漏掉它，就会退回到官方源 - URL 必须是 HTTPS 且末尾带
/：比如https://mirrors.aliyun.com/composer/✅，少斜杠会拼出/composerpackages.json导致 404，然后静默回退
验证是否真写进去了？在 CI 脚本里加一行：composer config -g repo.packagist。输出必须是完整 JSON 对象，形如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、或还是 https://packagist.org，说明没落进 runner 用户的配置文件里。
composer.json 里写 repositories 才真正可靠
全局配置只对当前 shell 用户有效，而 GitLab Runner、GitHub Actions、宝塔 www 用户，几乎从不用你本地的身份运行命令。项目级配置能提交进 Git，所有环境行为一致，且优先级高于全局。
进项目根目录后执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意不加 -g）：
- 如果
composer.json原有"repositories": {}，它会自动转为数组并插入 packagist 条目 - 如果已是
"repositories": []，它向末尾追加，不破坏已有私有源（如 Git 地址） - 如果根本没
repositories字段，它会新建，key 固定为"packagist"，不能自定义成"aliyun"
⚠️ 别手写 JSON：少一个逗号、引号不闭合、或多一个空格，CI 直接报 JSON decode error 失败。
换镜像后 composer install 还是走官方源？清缓存和旧文件
Composer 会优先读 composer.lock 和本地缓存里的元数据地址。哪怕你刚配好镜像，它也可能还在用旧 URL 下载——因为 lock 文件记录的是旧源下的 dist 地址和 hash。
必须做三件事：
- 运行
composer clear-cache - 删掉项目下的
vendor/和composer.lock - 再执行
composer install -vvv，观察日志是否出现GET https://mirrors.aliyun.com/composer/p2/...
别缓存 vendor/ ——不同 PHP 版本、扩展或 OS 下生成的 autoloader 不能混用，缓存错版本会导致 Class not found 或 Cannot declare class。真正该缓存的是 ~/.composer/cache，它只跟 composer.lock 哈希绑定，与环境无关。
CI 脚本里必须加 --no-dev --prefer-dist --optimize-autoloader --classmap-authoritative
这不是“锦上添花”的参数，是生产构建底线配置：
-
--no-dev：跳过开发依赖，减少下载量和解析时间 -
--prefer-dist：强制走 ZIP 包而非 Git clone，国内镜像对 dist 支持最稳 -
--optimize-autoloader和--classmap-authoritative：避免运行时类查找开销，尤其对 Laravel/Symfony 类多的项目效果明显
顺带一提：-vvv 不是调试选项，它是唯一能确认“到底走哪个源”的证据；--no-cache 也得加上，否则容器可能复用旧缓存（含官方源元数据），导致解析失败或回退。
composer.lock content-hash 是 32 位 md5）若没声明 repositories 字段，全局镜像对其无效——Composer 2.2+ 默认启用 packagist.org 隐式兜底，但镜像未必同步 v3.x 等旧包，结果就是 Could not find package。这类项目必须用项目级配置禁用兜底，或重生成 lock 文件。
