镜像源配置必须用 repo.packagist（单数），非 repos.packagist；CI 中需以当前用户执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，输出完整 JSON 且 URL 末尾带 / 才生效；应缓存 ~/.composer/cache（非 vendor/），并强制使用 --no-dev --prefer-dist --optimize-autoloader --classmap-authoritative 四参数组合。
镜像源配置必须用 repo.packagist，不是 repos.packagist
CI脚本里执行 composer config -g repos.packagist 看似合理，但会静默失败——Composer 2.x+ 只认 repo.packagist（单数），多一个 s 就写不进配置，composer config -g repo.packagist 输出为空或 null 就是这个原因。
验证方式很简单：composer config -g repo.packagist 必须输出完整 JSON 对象，形如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。URL 末尾必须带 /，否则部分镜像服务拒绝响应。
- 旧版 Composer（1.x）确实要用
repos.packagist，但 CI 环境基本都该升到 2.5+，别为兼容 1.x 埋坑 - 在 GitHub Actions 中用
sudo composer config -g，实际写进了 root 的~/.composer/config.json，而 runner 是ubuntu用户，根本读不到 - GitLab CI 同理，确保用当前用户身份执行，比如加
user: $(whoami)或直接去掉sudo
~/.composer/cache 是唯一值得缓存的路径
缓存 vendor/ 是常见误区。不同 PHP 版本生成的 autoload_classmap.php、APCu 开关状态、甚至文件系统大小写敏感性，都会导致缓存复用后出现 Class not found 或 Cannot declare class。真正与环境解耦、只依赖 composer.lock 哈希的是 ~/.composer/cache。
GitHub Actions 示例中，key 应基于 lock 文件哈希：${{ hashFiles('**/composer.lock') }}；GitLab CI 则推荐用 cache: key: $CI_PHP_VERSION-composer-cache。
- 缓存路径写成
~/.composer/cache，不是$COMPOSER_HOME/cache—— 某些 CI 镜像里COMPOSER_HOME未设或指向错误位置 - 如果项目用了自定义缓存目录（如
COMPOSER_CACHE_DIR=/tmp/composer-cache），CI 脚本里必须显式设置并缓存该路径 -
vendor/bin/是符号链接，缓存vendor/时若未排除它，可能在不同 runner 上指向错误路径，引发命令找不到
CI 中 composer install 必须带这四个参数
--no-dev --prefer-dist --optimize-autoloader --classmap-authoritative 这组参数不是“可选优化”，而是 CI 构建的硬性要求。漏掉任意一个，安装时间就可能从 30 秒跳到 3 分钟以上。
--no-dev 不只是省时间，更是安全边界：dev 依赖里的 phpunit、symfony/var-dumper 等工具若混入生产镜像，可能暴露调试入口或引入未审计的远程调用。
-
--prefer-dist强制走 zip 包而非 git clone，但注意它不跳过元数据刷新——所以必须配合镜像源才有效 -
--optimize-autoloader（简写-o）生成静态类映射表，Laravel/Symfony 项目 autoload 性能提升明显 -
--classmap-authoritative（简写-a）告诉 autoloader “没在映射里=真没有”，彻底跳过文件扫描——仅限 CI/生产，开发环境加了会导致新增类不生效
预分发 ≠ 多写几个 repositories
把阿里云、腾讯云、官方源全塞进 composer.json 的 repositories 数组，不会自动 fallback。Composer 按顺序合并元数据，下载时只认第一个提供该包完整信息的源。某个镜像超时或返回 502，整个安装就卡死，不会试下一个。
真要实现预分发和故障转移，得靠插件：composer global require yunwuxin/composer-plugin-mirror。它接管下载逻辑，在失败时按配置顺序重试镜像地址。
- 插件配置里每个镜像都必须声明
packages字段，填["*"]才能承接全部包 - 键名按字母序排序，所以用
mirror1、mirror2控制优先级，别用a、b - 项目级配置不如全局插件稳定——CI 中每次 checkout 都是干净环境，插件装一次即可，不用反复配
镜像源、缓存路径、安装参数、插件 fallback，四者缺一不可。少一个，CI 里的 Composer 就还在原地打转。
