镜像源是否生效需执行composer config -g repo.packagist，输出必须为完整JSON对象如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，空、null、纯URL字符串或官方地址均说明未生效，常见原因包括键名拼错（如repos.packagist）、缺末尾斜杠、用sudo写入root配置等。
确认镜像源是否真正生效
执行 composer config -g repo.packagist，输出必须是完整 JSON 对象，例如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空值、null、纯字符串 URL（如 "https://mirrors.tuna.tsinghua.edu.cn/composer/"）或仍是 https://packagist.org，都说明没生效。
常见静默失败点：
-
repos.packagist（多一个s）——字段名拼错，Composer 不报错但忽略 - 旧版 Composer 1.x 不支持
repo.packagist，得用composer config -g repos.packagist '{"type":"composer","url":""}' - CI 脚本里用了
sudo composer config -g，写进了 root 的配置，但 runner 是普通用户，读不到 - URL 缺末尾斜杠（如
https://mirrors.tuna.tsinghua.edu.cn/composer→ 必须是https://mirrors.tuna.tsinghua.edu.cn/composer/）
验证是否真走镜像：加 -vvv 运行 composer install，日志中出现 GET https://mirrors.aliyun.com/composer/p2/ 才算成功。
缓存目录必须挂载到高速本地盘
缓存目录若指向 NFS、Docker volume 或慢速磁盘，缓存就等于没用。默认路径在 $COMPOSER_HOME/cache（Linux/macOS）或 %APPDATA%\Composer\Cache（Windows），但 CI 容器生命周期短，需显式指定并挂载。
推荐做法：
- 设为本地 SSD 路径，例如
composer config -g cache-dir "/tmp/composer-cache" - CI 中用环境变量更可靠：
COMPOSER_CACHE_DIR=$HOME/.composer-cache-$PHP_VERSION，避免多 PHP 版本混用 - GitLab CI 示例：
paths: - ~/.composer-cache-8.2；GitHub Actions 推荐用actions/cache@v4，path精确到~/.composer/cache/files
注意：~/.composer/cache/files 是实际存放 zip 包的位置，只缓存 vendor/ 或只缓存顶层 ~/.composer/cache 都不完整——前者跳过包复用，后者仍要重复解压校验。
CI 中 composer install 必须带的参数组合
漏掉任意一个，缓存就白配：
-
--no-dev：跳过require-dev，省掉 30%–60% 时间 -
--prefer-dist：强制走 tarball 安装，比--prefer-source更快更稳定；即使某包没 dist，Composer 也会自动 fallback，不用怕 -
--optimize-autoloader（或-o）：生成vendor/composer/autoload_classmap.php，把 PSR-4 映射转成类名直查表
这三项在生产构建中缺一不可。尤其 --prefer-dist，它绕过了 Git clone 和 checkout，对私有仓库也适用（前提是提供 dist 包）。
检查 classmap-authoritative 是否误启
该配置启用后，自动加载器会认为“类不在映射里 = 类不存在”，彻底跳过 PSR-4 文件扫描。对大多数项目是安全的，但以下场景会出问题：
- 运行时动态生成类（如 Doctrine Proxy、Laravel Octane 的热重载类）
- 依赖中含
files类型 autoload（如某些旧扩展包通过include加载辅助函数） - 测试中手动
eval()或create_function()定义类（已废弃但仍有遗留）
上线前务必确认：composer.json 中未设置 "classmap-authoritative": true，或已在 CI 命令中显式禁用（如 composer install --no-authoritative）。它和 apcu-autoloader 不能共存，且一旦启用，composer dump-autoload 必须重新生成全量映射。
