缓存路径配错导致Composer根本未生效，需验证cache-files-dir是否非空、确认COMPOSER_CACHE_DIR已加载、确保PHP版本/lock文件/镜像源三者一致。
Composer 缓存路径配错，等于没缓存——不是速度慢，而是根本没生效。
缓存路径不生效的三个典型现象
执行 composer install 时反复下载同一包；composer config -g cache-files-dir 输出为空或指向临时目录；CI 构建中 ~/.composer/cache 占用磁盘但命中率始终为 0。
- 根本原因常是环境变量未透传：Docker 容器里没设
COMPOSER_CACHE_DIR，或 CI 脚本里用composer config --global cache-dir改了但进程没读它 -
cache-files-dir必须指向files子目录（如/tmp/composer-cache/files），只配到父目录无效 - Windows 下若用
%APPDATA%\Composer\Cache，需确保路径是绝对路径且无空格、中文，否则 Composer 会静默 fallback 到默认路径
如何验证当前缓存路径是否真正生效
别只看 composer config -g cache-dir 的输出——它只显示配置值，不反映实际运行时行为。
- 运行
composer config -g cache-files-dir，必须返回非空路径；若为空，立刻补上：composer config -g cache-files-dir ~/.composer/cache/files - 执行一次
composer clear-cache后再composer install，立刻检查该路径下是否生成了files/子目录及哈希命名的 zip 包 - 在 PHP CLI 环境中运行
php -r "echo getenv('COMPOSER_CACHE_DIR');"，确认变量已加载（尤其 Docker 或 CI 中）
CI/CD 和 Docker 中必须同步的三要素
缓存能复用的前提，不是“路径对了”，而是 PHP 版本、composer.lock 内容、镜像源 URL 三者完全一致。任一变动，缓存即失效。
立即学习“PHP免费学习笔记（深入）”；
- GitHub Actions 中用
actions/cache@v4时，key必须含hashFiles('**/composer.lock')，不能只用runner.os - Docker 构建时，把
COPY composer.json composer.lock ./放在COPY . .之前，并挂载缓存卷：-v $(pwd)/.composer-cache:/root/.composer/cache - 镜像源地址也参与缓存 key 计算：如果本地开发用阿里云镜像，CI 却走默认源，缓存文件虽存在，但 Composer 会拒绝使用（校验失败）
最容易被忽略的是：缓存路径和镜像源必须成对锁定。改了镜像却没清旧缓存，或换了 PHP 小版本但没更新缓存 key，都会让缓存变成“幽灵目录”——看着在，实则从不命中。
