离线打包前必须清理三类缓存：1）~/.composer/cache/files/、2）~/.composer/cache/repo/、3）sys_get_temp_dir()下的composer_.zip和php.phar；因composer clear-cache不清理repo/和临时目录，且不校验完整性，残留损坏包会导致解压失败。
离线打包前必须清理哪些缓存位置
离线打包（如 composer install --no-interaction --prefer-dist --no-scripts）依赖的是已下载的压缩包和元数据快照，但这些内容可能来自过期或损坏的缓存。真正要清的不是 vendor/，而是三类：1）~/.composer/cache/files/（已下载的 .zip 包）、2）~/.composer/cache/repo/（packages.json 索引）、3）sys_get_temp_dir() 下残留的 composer_*.zip 或 php*.phar——后者常被忽略，却会导致离线时解压失败。
为什么 composer clear-cache 在离线前不够用
composer clear-cache 默认跳过 vcs/ 和 repo/ 子目录中的部分文件（尤其 Packagist 元数据），且完全不碰系统临时目录。更关键的是：它不校验缓存完整性，删完仍可能留着损坏的 .zip 文件。离线环境下没有网络回退机制，一个坏包就会让整个 install 中断并报 file could not be downloaded。
- 加
--no-interaction是必须的，否则在无 TTY 的离线构建中会卡住 - 运行前先确认路径：
composer config --global cache-dir，避免误删空路径或 NFS 挂载点 - 务必手动清一次
sys_get_temp_dir()：rm -f $(php -r "echo sys_get_temp_dir();")/composer_*.zip
推荐的离线打包前清理脚本
不要只靠一条命令。下面这个组合能覆盖 99% 的离线失败场景：
composer clear-cache --no-interaction rm -rf ~/.composer/cache/repo/https---packagist.org/ rm -rf ~/.composer/cache/files/ rm -f $(php -r "echo sys_get_temp_dir();")/composer_*.zip rm -f $(php -r "echo sys_get_temp_dir();")/php*.phar
注意：~/.composer/cache/vcs/ 不用清（离线打包不用 Git 克隆），但如果你之前用过 --prefer-source，就得加上 rm -rf ~/.composer/cache/vcs/。
清理后如何验证是否真“干净”
执行完清理，别直接跑 install。先做两件事：
- 检查缓存目录是否为空：
ls -A ~/.composer/cache/应返回空（或只剩cache.lock） - 模拟离线拉取：
composer install --dry-run --no-interaction 2>&1 | grep -E "(Downloading|failed|could not)"，若出现Downloading就说明还有缓存没清干净 - 特别留意
sys_get_temp_dir()是否被 IDE 或杀软锁住——lsof +D $(php -r "echo sys_get_temp_dir();")（Linux/macOS）可查占用进程
离线打包最脆弱的环节从来不是网络，而是你以为“已经清了”的那些临时文件。它们藏得深、命名随机、不进日志，但只要剩下一个损坏的 composer_*.zip，整个构建链就停在第一行错误里。
