Composer因disk_free_space()在NFS等文件系统返回false或0而误报磁盘不足；可通过COMPOSER_CACHE_DIR指向正常路径、--no-cache跳过缓存或CI中用--no-cache--prefer-dist绕过检测。
为什么 Composer 会触发 disk_free_space 报错
Composer 在执行 install 或 update 前，会调用 PHP 的 disk_free_space() 函数检查目标磁盘剩余空间（默认是 vendor/ 所在分区）。当该函数返回 false（例如 NFS 挂载、某些容器文件系统、权限受限或 FUSE 文件系统），或返回值异常小（如 0），Composer 就会中止并报类似：Failed to write cache file: disk_free_space(): No space left on device —— 实际磁盘明明还有几十 GB 空闲。
绕过磁盘空间检测的可行方式
Composer 本身不提供官方开关禁用空间检测，但可通过以下几种方式规避：
- 设置环境变量
COMPOSER_CACHE_DIR指向一个真实可写且能正确返回disk_free_space()值的路径（比如宿主机本地目录），让缓存层不走问题挂载点 - 使用
--no-cache参数跳过所有缓存读写（包括disk_free_space检查），适合 CI 环境或临时构建 - 在容器或部署脚本中，提前创建一个最小可用的 tmpfs 或 bind mount（如
/tmp/composer-cache），再通过COMPOSER_CACHE_DIR指向它 - 若你控制 PHP 运行环境，可 patch
disk_free_space()行为（不推荐生产环境）：在 Composer 启动前注入一个 wrapper 函数，对特定路径返回合理值
COMPOSER_CACHE_DIR 设置示例与注意事项
这是最稳定、无需改源码的方式。注意路径必须存在、可写，且所在文件系统支持 disk_free_space() 正常返回整数。
export COMPOSER_CACHE_DIR="/tmp/composer-cache" mkdir -p $COMPOSER_CACHE_DIR composer install --no-interaction
常见错误：
- 路径不存在或权限不足 → Composer 仍会 fallback 到默认缓存目录并再次失败
- 指向 NFS 或 /dev/shm（某些内核版本下
disk_free_space()返回false）→ 问题照旧 - 未导出为环境变量（仅 shell 变量）→ Composer 进程无法继承
CI/CD 中推荐的轻量级绕过方案
在 GitHub Actions、GitLab CI 等场景，直接禁用缓存最省事，也避免污染构建环境：
composer install --no-cache --no-interaction --prefer-dist
这会跳过所有缓存逻辑（包括空间检测），且强制走 dist 包（更快）。只要网络通畅、包版本锁定（composer.lock 存在），行为完全可靠。不要试图在 CI 中“修复”挂载问题——绕过才是正解。
真正难处理的是开发机上长期挂载的 WSL2 / Docker Desktop 共享目录，那里 disk_free_space() 失效是已知限制，必须靠 COMPOSER_CACHE_DIR + 本地路径解耦。
