Composer解压失败的根源是sys_get_temp_dir()返回的临时目录,而非cache-dir或vendor-dir;该目录在Linux/macOS为/tmp、Windows为%LOCALAPPDATA%\Temp,需检查其空间、inode、权限及ZipArchive可用性。

Composer解压失败时,sys_get_temp_dir()才是真凶
Composer解压 ZIP 包不走 cache-dir 或 vendor-dir,它全程依赖 PHP 的 sys_get_temp_dir() 返回路径。这个目录在 Linux/macOS 上通常是 /tmp,Windows 上是 %LOCALAPPDATA%\Temp。你改了所有 Composer 配置,但 ZipArchive::extractTo(): failed to open stream 依然报错——大概率是这里卡住了。
常见现象包括:
-
zlib_decode(): data error后紧跟解压失败 - CI 构建偶尔成功、偶尔失败,且无规律
-
composer create-project卡在 “Extracting archive” 步骤不动
验证方法很简单:php -r "echo sys_get_temp_dir();",然后进那个目录看有没有堆积大量 composer_*.zip 或 php*.phar 文件。尤其注意 df -i /tmp ——inode 耗尽比磁盘空间满更隐蔽,也更致命。
TMPDIR 环境变量能绕过系统默认临时目录
你不能改 sys_get_temp_dir() 的返回值,但可以覆盖它的源头:环境变量 TMPDIR(Linux/macOS)或 TEMP/TMP(Windows)。这是最直接、最安全的干预方式。
操作建议:
- 先创建一个大分区下的专用临时目录:
mkdir -p /mnt/bigdisk/tmp && chmod 777 /mnt/bigdisk/tmp - 运行前导出:
export TMPDIR="/mnt/bigdisk/tmp"(Linux/macOS)或set TMPDIR=C:\temp(Windows CMD) - 确认生效:
php -r "echo sys_get_temp_dir();"应该输出新路径 - CI 脚本中务必在
composer install前设置,避免被 runner 默认环境覆盖
注意:COMPOSER_CACHE_DIR 和 TMPDIR 完全无关——前者只管 ZIP 包存哪,后者才管解压时写哪。别指望清缓存能解决解压失败。
ZipArchive不可用?先查扩展再查权限
ZipArchive 是 Composer 解压的默认引擎,但它不是总可用。很多服务器禁用 proc_open,或没装 zip 扩展,或 PHP 编译时没带 zlib 支持——这些都会导致解压流程静默 fallback 到更脆弱的纯 PHP 实现,甚至直接失败。
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
必须逐项验证:
-
php -r "new ZipArchive();"不报错才算实例化成功 -
php -r "echo ZIPARCHIVE::CHECKSUM_CRC32;"有数字输出,说明常量可用 -
php -m | grep zip确认zip扩展已启用 -
ls -l $(php -r "echo sys_get_temp_dir();")看目录是否可写(尤其 Docker 容器内,/tmp可能是只读挂载)
如果以上任一失败,COMPOSER_UNZIP=7zip composer install 是更稳的选择——前提是宿主机已安装 7z 或 7zz,且路径在 $PATH 中。
Docker 场景下 /tmp 挂载冲突最容易被忽略
Docker 默认把 /tmp 映射为 tmpfs(内存文件系统),大小受容器内存限制。一旦 Composer 在里面解压大包,很容易触发 OOM 或写满 tmpfs 限额,而错误日志里根本不会提“tmpfs size limit”。更麻烦的是,如果你在 docker-compose.yml 里同时写了:
tmpfs: /tmp volumes: - ./cache:/tmp
那后定义的 volumes 会覆盖 tmpfs,但实际效果取决于 Docker 版本和挂载顺序——有时你看到的是空目录,有时是旧数据残留,调试起来毫无头绪。
稳妥做法:
- 彻底避开容器内
/tmp,用TMPDIR=/var/tmp并挂载宿主机大分区目录到/var/tmp - 禁用 tmpfs 挂载,除非你明确需要内存级临时存储
- CI 中每个 job 使用独立
COMPOSER_CACHE_DIR+ 独立TMPDIR,避免并发写冲突
真正难缠的从来不是 Composer 本身,而是它悄悄依赖的系统层临时目录——那里没有日志、没有配置项、也没有错误提示,只有静默失败和随机崩溃。

















