Composer当前实际缓存路径须用composer config --global cache-dir命令确认，输出即真实路径；若为空则走默认路径（Linux/macOS为~/.composer/cache，Windows为%APPDATA%\Composer\Cache），但受COMPOSER_CACHE_DIR环境变量优先覆盖且不解析波浪号。
Composer 缓存路径不是固定死的，它由环境变量、全局配置和运行时权限共同决定；直接查 composer config --global cache-dir 才是唯一可靠方式，别猜、别翻文档、别看 ~/.composer/cache 是否存在。
怎么确认 Composer 当前实际用的缓存路径
很多人改了配置却没生效，是因为根本没确认 Composer 此刻读的是哪个路径。命令输出即真实路径，不依赖任何假设：
- 运行
composer config --global cache-dir，它会直接打印当前生效值；如果为空，说明没配过，走默认路径 - Linux/macOS 默认是
~/.composer/cache，但~指向当前用户家目录，root用户下就是/root/.composer/cache - Windows 默认是
%APPDATA%\Composer\Cache，注意不是%LOCALAPPDATA%，也不是%USERPROFILE% - 如果设置了
COMPOSER_CACHE_DIR环境变量，它会优先于配置文件，且不支持~展开——必须写绝对路径
修改缓存路径最稳的操作流程
用 composer config --global cache-dir 写入是最安全的方式，它自动更新 config.json，不碰其他字段：
- 先确保目标目录存在且当前用户有读写权限：
mkdir -p /data/composer-cache && chown $USER:$USER /data/composer-cache - 执行
composer config --global cache-dir /data/composer-cache，不要带引号、不要用~ - 立刻验证：
composer config --global cache-dir输出应与你刚设的一致 - 旧缓存不会自动迁移，要手动搬或删；新
install会直接写新路径，旧路径残留无影响
为什么改完还是往 ~/.composer/cache 写
常见原因不是命令没执行，而是路径被更高优先级机制覆盖：
-
COMPOSER_CACHE_DIR环境变量已设置，且值为~/.composer/cache（注意：Composer 不解析~，所以这其实是个无效路径，会导致静默 fallback 到默认） - 在 Docker 或 CI 中用了
sudo composer ...，结果配置写进了root的config.json，但构建时以普通用户运行，读的是自己的配置 - 项目根目录有
composer.json并定义了"config": {"cache-dir": "..."}，它会覆盖全局设置 - PHP 进程启动时未加载最新环境变量（如 tmux/zsh 会话未重载配置，或 IDE 终端未重启）
缓存路径设错的典型报错和应对
路径不可写或不存在时，Composer 不会提前报错，而是在首次 install 或 update 时失败，错误信息明确指向路径问题：
-
file_put_contents(/xxx/cache/repo/https---packagist.org/packages.json): failed to open stream→ 路径不存在或权限不足 -
Cache directory does not exist→clear-cache时路径为空或无效，通常因COMPOSER_CACHE_DIR设错 - 执行
composer install后du -sh $(composer config --global cache-dir)仍为 0 → 缓存根本没写进去，先检查该路径是否真被使用（用strace -e trace=openat composer install 2>&1 | grep cacheLinux 下可验证） - CI 中挂载缓存目录后仍慢 → 检查挂载路径 UID 是否匹配，
ls -ld /path/to/mounted/cache看属主是否为当前运行用户
真正麻烦的不是改路径，而是改完后没人验证它是否被 Composer 进程实际访问——尤其在容器、CI、多用户共用机器等场景，路径“看起来对”，但进程根本没读到。每次修改后，务必用 composer config --global cache-dir 和 ls -l 双重确认。
