--prefer-dist断网失败是因为依赖解析需远程获取packagist元数据，而非仅下载dist包；必须联网完成首次安装、生成含dist字段的lock文件，并用--no-network跳过网络请求。
为什么 --prefer-dist 在断网时会失败？
composer install 加了 --prefer-dist，本意是跳过源码克隆、直接下 tarball 压缩包，但断网后它连 packagist.org 的元数据都拉不到，根本不知道该下哪个 .tar.gz、校验值是多少。不是“有缓存就能用”，而是整个依赖解析流程卡在远程元数据获取阶段。
- Composer 默认每次运行都会尝试刷新
packages.json元数据（哪怕本地有缓存） -
--prefer-dist不影响元数据获取行为，只影响后续安装方式 - 断网时
composer install会报错：Could not fetch <a href="https://www.php.cn/link/c5b3da73adacd81b5962e60b6b987e52">https://www.php.cn/link/c5b3da73adacd81b5962e60b6b987e52</a>
断网前必须做好的三件事
只有提前准备，断网后才能无感切到本地 dist 包。这不是事后补救，而是前置动作：
- 运行过一次完整的
composer install --prefer-dist（联网状态下），确保所有 dist 包已下载并存入~/.composer/cache/files/ - 确保项目根目录存在有效的
composer.lock（含完整dist字段：url、shasum、type） - 执行过
composer install --no-interaction至少一次，让 Composer 把 lock 文件里记录的 dist 信息真正落地为可复用的缓存结构
漏掉任意一条，断网时 --prefer-dist 都会退化成报错或自动 fallback 到 --prefer-source。
断网后唯一可靠命令：加 --no-network
不加这个标志，Composer 仍会尝试连接 repo，哪怕你本地缓存齐全。正确姿势是：
composer install --prefer-dist --no-network
-
--no-network强制跳过所有 HTTP 请求，只读composer.lock和本地缓存 - 它会严格按 lock 文件里的
dist.url拼出缓存路径，例如：vendor/symfony/console/123abc.tar.gz→ 对应缓存文件~/.composer/cache/files/symfony/console/123abc.zip - 如果某包的 dist 缓存缺失（比如你删过缓存、或之前没装过），会直接报错：
Package symfony/console has no distribution archive available—— 这说明它真的不在本地，不是网络问题
缓存路径和校验失效的坑
Composer 的 dist 缓存不是“下了就永久有效”。几个关键细节常被忽略：
- 缓存文件名由
shasum决定，lock 文件里改了 shasum，就算同个 URL 也会被当作新包重新下（断网时就失败） -
~/.composer/cache/files/下的子目录结构是vendor/name/sha1sum.zip，手动放错位置或改名无效 - PHP 版本、平台配置（如
ext-zip是否启用）会影响 dist 解压行为，断网时这些环境必须和上次联网安装时一致 - Windows 用户注意：缓存路径在
%APPDATA%\Composer\Cache\files\，别去 Linux 路径找
断网场景下，最脆弱的环节从来不是命令怎么写，而是「你以为缓存还在，其实它已经被清理或版本不匹配」。
