--prefer-cache 仅当 composer.lock 中版本与本地缓存 ZIP 包的 commit hash 完全匹配时才生效，否则仍走网络下载；它不跳过元数据请求、不改变包发现逻辑、不绕过校验，仅适用于 CI/CD 预填充缓存场景。
Composer 默认不会优先从缓存读取包，--prefer-cache 是一个被广泛误解的参数——它只在特定条件下生效，且不能“强制跳过网络请求”。
为什么 --prefer-cache 经常没效果？
这个参数仅对 composer install 和 composer update 中已存在于本地缓存（~/.composer/cache 或 COMPOSER_CACHE_DIR 指定路径）的包起作用，并且前提是：当前项目 composer.lock 中记录的包版本与缓存中可用的 ZIP 包完全匹配（包括 exact commit hash 或 dist reference）。只要缓存里缺一个包、或 hash 对不上，Composer 仍会走网络下载。
- 它不改变包发现逻辑（如从 packagist.org 获取元数据）
- 它不跳过
packagist.org的GET /packages/list.json请求 - 它不绕过 vendor 目录写入前的完整性校验
--prefer-cache 的真实使用场景
适合在 CI/CD 流水线中配合预填充缓存使用，例如 GitHub Actions 中用 actions/cache 缓存 ~/.composer/cache，再运行：
composer install --prefer-cache --no-interaction
此时若所有依赖 ZIP 包已在缓存中且未过期（默认缓存有效期为 15 天），Composer 才会解压缓存 ZIP 而非重新下载。否则仍 fallback 到网络。
- 必须搭配
--no-interaction避免卡在交互提示 - 需确保
composer.lock未被修改，否则 hash 不匹配导致缓存失效 - 对
require新包或升级版本等操作基本无效
比 --prefer-cache 更可靠的离线方案
真要避免网络依赖，得靠本地镜像或离线包仓库：
- 用
composer config repo.packagist composer https://your-mirror.com指向私有镜像 - 用
composer archive打包整个 vendor + lock，分发后用composer install --no-network - 设置
COMPOSER_DISABLE_NETWORK=1环境变量，但要求所有包 ZIP 已提前放入缓存目录且可解压
注意：--no-network 是硬性断网开关，一旦缓存缺失或损坏，命令直接失败，错误信息通常是 Failed to download xxx: No zip found for xxx。
缓存路径和清理验证技巧
确认缓存是否真被命中，看 Composer 输出中是否出现 Using version x.x.x for xxx from cache；如果看到 Downloading xxx 或 Downloading (connecting...)，说明没走缓存。
- 查当前缓存位置：
composer config --global cache-dir - 手动清空缓存（调试时常用）：
composer clear-cache - 查看某包缓存状态：
ls -la $(composer config --global cache-dir)/repo/https---packagist.org/provider-xxx.json
缓存 ZIP 文件实际存在 cache-dir/files/ 下，命名含 vendor/name 和 hash，但别手动删——用 clear-cache 更安全。
