COMPOSER_CACHE_DIR必须设绝对路径,不支持~或$HOME等shell展开;需完整、可写、无中文空格,并重启终端验证;其与COMPOSER_HOME并列独立,不可互相替代。

COMPOSER_CACHE_DIR 必须设绝对路径,不能用 ~ 或 $HOME
Composer 缓存路径不认 shell 展开符号,COMPOSER_CACHE_DIR=~/.composer/cache 或 COMPOSER_CACHE_DIR=$HOME/.composer/cache 全部失效——它会悄悄退回到默认位置(Linux/macOS 是 ~/.cache/composer,Windows 是 %LOCALAPPDATA%\Composer\Cache),且不报错、不提示。
正确写法只有一种:COMPOSER_CACHE_DIR=/home/alex/composer-cache(Linux/macOS)或 COMPOSER_CACHE_DIR=C:\Users\alex\AppData\Local\Composer\Cache(Windows)。路径必须完整、可写、无中文、无空格。
- 设完后必须重启终端(
source ~/.zshrc不够,子进程如 VS Code 终端不会继承) - 验证方式:运行
composer config --list --global,找 “Cache directory” 行,确认路径与你设置一致 - 若输出仍是默认路径,说明环境变量未生效或被覆盖(比如在 Dockerfile 里用了
ENV COMPOSER_CACHE_DIR却没进用户 shell)
缓存路径和 COMPOSER_HOME 的关系不是父子,而是并列
COMPOSER_HOME 控制配置文件、全局 vendor、插件等存放位置;COMPOSER_CACHE_DIR 单独控制下载包、元数据、zip 解压临时文件的缓存位置。两者互不影响,可以分开放——比如把 COMPOSER_HOME 放 SSD,COMPOSER_CACHE_DIR 放大容量 HDD。
但要注意:如果只设了 COMPOSER_HOME 而没设 COMPOSER_CACHE_DIR,缓存仍走默认路径;反之亦然。不存在“设了 HOME 就自动接管 cache”的逻辑。
- 常见误操作:在
~/.zshrc里只写了export COMPOSER_HOME=...,以为缓存也跟着挪了,结果 CI 流水线磁盘爆满——其实是缓存还在~/.cache/composer - CI 场景建议显式指定两者:
COMPOSER_HOME=/tmp/composer-home COMPOSER_CACHE_DIR=/tmp/composer-cache,避免污染构建机用户目录 - Docker 中应使用
ENV指令而非RUN export,否则只在当前层生效
composer clear-cache 失效?先确认你清的是哪个缓存
composer clear-cache 只清 COMPOSER_CACHE_DIR 下的内容,对 COMPOSER_HOME 里的 cache/ 子目录(旧版 Composer 1.x 风格)或 repo/(镜像索引)完全无效。
如果你改过 COMPOSER_CACHE_DIR,但 clear-cache 后发现磁盘没释放,大概率是以下之一:
- 旧缓存还留在默认路径(
~/.cache/composer或%LOCALAPPDATA%\Composer\Cache),手动删掉 - 全局配置中
cache-dir字段被硬编码(检查composer config --global --list输出里是否有cache-dir行),优先级高于环境变量,得用composer config --global --unset cache-dir清除 - 某些插件(如
hirak/prestissimo)自己建缓存目录,不在 Composer 管理范围内
Windows 上 %LOCALAPPDATA% 不展开,别直接写进环境变量
PowerShell 或 CMD 中设 set COMPOSER_CACHE_DIR=%LOCALAPPDATA%\Composer\Cache 看似合理,但 Composer 进程启动时根本不会解析这个变量——它只认字面量路径。结果就是缓存照旧写进默认位置,而你看到的 echo %COMPOSER_CACHE_DIR% 显示正常,极具迷惑性。
唯一可靠做法:用完整路径,或在 PowerShell 中用 $env:COMPOSER_CACHE_DIR = "$env:LOCALAPPDATA\Composer\Cache"(注意是 $env:,不是 %)。
- Git Bash 用户更麻烦:
%LOCALAPPDATA%根本不识别,必须切到 PowerShell 或 CMD 执行设置 - 验证是否真生效:运行
composer config --list --global,看 “Cache directory” 是否为完整路径,而不是含%符号的字符串 - 系统级环境变量修改后,所有已打开的 CMD/PowerShell 必须关闭重开,
echo %PATH%出现新路径才代表生效


















