必须用绝对路径，因Composer不解析~、$HOME或相对路径；目录需手动创建并确保当前用户有读写权限；环境变量COMPOSER_CACHE_DIR优先级更高，会直接覆盖配置。
必须用 composer config --global cache-dir 设置绝对路径，手动创建目录并确保当前用户有读写权限；环境变量 COMPOSER_CACHE_DIR 优先级更高，会直接覆盖配置。
为什么 composer config --global cache-dir 必须写绝对路径
Composer 完全不解析 ~、$HOME 或相对路径（如 ./cache）。写 ~/composer-cache 或 ../cache 后，命令看似成功，但后续 composer install 仍走默认路径，且无任何提示。
- Windows 正确示例：
composer config --global cache-dir "D:\composer-cache"（含英文双引号，防空格/反斜杠出错） - Linux/macOS/WSL 正确示例：
composer config --global cache-dir /data/composer-cache - 错误写法：
composer config --global cache-dir ~/.composer/cache（会被忽略）
目录必须手动创建且权限正确，否则静默失败
Composer 从不自动创建缓存目录。路径不存在或权限不足时，它不会报错，而是悄悄 fallback 到默认位置（如 %APPDATA%\Composer\Cache 或 ~/.composer/cache），导致你以为改成功了，其实没生效。
- Windows：在 CMD 或 PowerShell 中运行
mkdir D:\composer-cache，再右键该目录 → “属性” → “安全” → 确保当前用户有“完全控制” - Linux/macOS/WSL：运行
mkdir -p /data/composer-cache && chmod 755 /data/composer-cache - CI/Docker 中若用 root 用户执行
composer config，但实际构建以www-data或gitlab-runner身份运行，需对目标目录执行sudo chown -R $USER:$USER /data/composer-cache
验证是否真正生效，别只看 config 输出
composer config --global cache-dir 显示的只是配置值，不代表运行时真实路径。真正起作用的是 Composer 运行时加载的路径，受 COMPOSER_CACHE_DIR 环境变量、全局配置、默认逻辑三级影响。
- 第一步：运行
composer config --global cache-dir，确认输出是你设的完整绝对路径 - 第二步：运行
composer diag，检查Cache directory:行是否匹配；如果不符，说明COMPOSER_CACHE_DIR被设了，或目录权限/存在性不满足 - 第三步：执行
composer clear-cache，观察日志中清理的是不是你的新路径；再跑一次composer install -vvv，搜索Writing into cache看路径是否一致
旧缓存不会自动迁移，要手动处理
改完路径后，原缓存（如 ~/.composer/cache）里的 files/、repo/、vcs/ 子目录不会被复制过去。继续用新路径会导致重复下载，尤其在 CI 中浪费时间和带宽。
- 推荐清空重来：
composer clear-cache && rm -rf ~/.composer/cache（Linux/macOS）或手动删 Windows 默认路径 - 如需保留，可手动同步：
rsync -a ~/.composer/cache/ /data/composer-cache/（注意末尾斜杠含义） - 项目级临时绕过（适合调试）：
COMPOSER_CACHE_DIR="$(pwd)/.composer-cache" composer install，提前mkdir -p .composer-cache && chmod 700 .composer-cache
最易被忽略的是：缓存路径只是前提，镜像源、PHP 版本、composer.lock 内容三者任意一个变动，都会让缓存失效——路径对了，但文件根本不会被复用。
