离线安装失败主因是 composer.lock 与缓存不匹配，关键在于 dist.shasum 对应文件缺失、repo/ 目录未迁移、composer_disable_network=1 未启用或缓存路径含中文。
离线安装前必须确认 composer.lock 与缓存是否匹配
报 Package not found 或 Could not fetch，大概率不是网络没关，而是 composer.lock 里某个包的 dist.shasum 在本地缓存中根本不存在。Composer 不模糊匹配，它严格按哈希值去 ~/.composer/cache/files/ 下找对应文件（如 monolog/monolog/7a8e0d4b12c3.zip）。
实操建议：
- 在联网机运行
composer show --all --locked，检查每个包的dist.type是否为zip或tar；若出现source，说明走了 Git 克隆，无法被缓存复用 - 用
find ~/.composer/cache/files -name "*${shasum:0:8}*.zip"手动验证关键包是否存在（${shasum:0:8}是dist.shasum前 8 位） - 确保两端 Composer 主版本一致（如都是 2.7.x），否则缓存结构不兼容，
files/目录下文件名规则可能不同
缓存路径含中文时会解析失败
Linux/macOS 下若缓存路径含中文（如 /home/张三/.composer/cache），file:// 协议 URL 会因未转义导致解析异常——Composer 内部调用 cURL 或 fopen 时可能把中文字符当非法 URI，报错 failed to open stream: No such file or directory。
实操建议：
- 迁移缓存前，在联网机运行
composer config --global cache-dir /tmp/composer-cache-en，强制使用纯英文路径 - 离线机上也统一设为英文路径：
composer config --global cache-dir /opt/composer-cache，再解压缓存包到该目录 - 不要依赖默认的
$HOME路径，尤其 Windows 用户：$env:USERPROFILE可能返回C:\Users\张三，应改用C:\composer-cache这类无中文路径
COMPOSER_DISABLE_NETWORK=1 是硬性开关，不是可选项
即使缓存齐全、composer.lock 正确，不设 COMPOSER_DISABLE_NETWORK=1 就运行 composer install，仍会卡在 Loading composer repositories 或报 Could not fetch https://repo.packagist.org/packages.json。这不是超时，是 Composer 在锁文件解析阶段主动发起的元数据请求。
实操建议：
- Linux/macOS：前置环境变量，如
COMPOSER_DISABLE_NETWORK=1 composer install --prefer-dist --no-plugins --no-scripts - Windows CMD：
set COMPOSER_DISABLE_NETWORK=1 && composer install --prefer-dist --no-plugins --no-scripts - PowerShell：
$env:COMPOSER_DISABLE_NETWORK="1"; composer install --prefer-dist --no-plugins --no-scripts
只复制 files/ 目录不够，必须完整迁移 cache 结构
Composer 缓存生效依赖三个子目录：files/（包压缩包）、repo/（元数据 JSON）、archived/（composer archive 生成的归档）。少任何一个，composer install --prefer-dist 都会 fallback 到联网尝试。
常见错误是只复制 files/，结果日志里仍出现 Fetching https://repo.packagist.org/packages.json——因为没 repo/，Composer 根本不知道某个包的 dist.shasum 对应哪个 ZIP 文件。
实操建议：
- 打包时必须包含整个缓存根目录，不要过滤或跳过隐藏文件
- 离线机上先运行
composer config --global cache-dir /path/to/restored/cache，再执行安装命令 - 验证是否成功：检查
$(composer config cache-dir)/repo/https---packagist.org/是否存在且含packages.json，files/下是否有对应 shasum 命名的 zip 文件
repo/ 目录有没有、COMPOSER_DISABLE_NETWORK=1 有没有生效、路径里有没有中文这三个点上。漏掉任意一个，都会让 Composer 在解析阶段就中断，连缓存文件都碰不到。
