唯一有效方式是设环境变量COMPOSER_CACHE_DIR；--cache-dir命令行参数根本不存在；全局配置需绝对路径、目录存在且权限正确；CI/Docker必须用环境变量；还需单独配置cache-vcs-dir。
唯一安全、跨平台且立即生效的方式是设环境变量 COMPOSER_CACHE_DIR；composer config --global cache-dir 仅适合单机长期使用，但易被覆盖或权限破坏；所有带 --cache-dir 的命令行写法都根本不存在，会直接报 Unknown option cache-dir。
为什么 composer install --cache-dir 一定失败？
Composer 命令行解析器压根不识别 --cache-dir 这个 flag。它不是隐藏参数，也不是文档遗漏项——源码里没定义，运行时直接抛错。你看到的任何“加参数临时改缓存”的教程，都在误导你浪费调试时间。
-
composer config cache-dir只读配置值，对install或update过程完全无影响 - 在
composer.json里写"config": {"cache-dir": "..."}同样无效，该字段只被composer config命令读取 - 真正起作用的只有三处：环境变量 → 全局 config → 默认路径；没有“命令行参数”这一层
怎么正确设置全局缓存路径（适合日常开发）
用 composer config --global cache-dir 是最常用方式，但它有硬性前提，漏一条就会静默失效：
- 路径必须是绝对路径，比如
/home/alex/composer-cache；~/composer-cache或./cache都不解析 - 目录必须已存在：
mkdir -p /home/alex/composer-cache - 当前用户必须有完整读写执行权限：
ls -ld /home/alex/composer-cache第三列应为你的用户名 - 改完后旧缓存不会迁移，要手动
rsync -a ~/.composer/cache/ /home/alex/composer-cache/或清空重来 - 验证是否真生效：运行
composer diag | grep "Cache directory"，不是composer config --global cache-dir
CI/Docker/多用户环境下必须用 COMPOSER_CACHE_DIR
环境变量优先级最高，启动即生效，不写磁盘、不依赖挂载点可读，最适合自动化场景：
- Linux/macOS：在 CI 脚本开头加
export COMPOSER_CACHE_DIR="/tmp/composer-cache"，再紧跟mkdir -p "$COMPOSER_CACHE_DIR" - Docker：在
Dockerfile中写ENV COMPOSER_CACHE_DIR=/cache，并确保-v $(pwd)/cache:/cache挂载且属主正确 - Windows PowerShell：
[Environment]::SetEnvironmentVariable("COMPOSER_CACHE_DIR", "D:\composer-cache", "User") - 关键陷阱：如果
echo $COMPOSER_CACHE_DIR有输出，但composer diag显示的路径不对，说明该变量没传进 Composer 进程（如 Docker 未用--env，或 GitHub Actions 未用env:块）
别忽略 cache-vcs-dir，否则 Git 包每次重 clone
cache-vcs-dir 和 cache-dir 完全独立，Composer 不会自动推导。如果你项目里用了私有 Git 仓库或 "type": "git" 的包，不单独配它，composer install 就会反复 git clone，缓存形同虚设：
- Linux/macOS：
composer config --global cache-vcs-dir "$COMPOSER_CACHE_DIR/vcs" - Windows：
composer config --global cache-vcs-dir "%COMPOSER_CACHE_DIR%\vcs" - 验证：
ls -l $(composer config --global cache-vcs-dir)应能看到类似github.com/monolog/monolog.git/的子目录 - 注意：这个配置必须在每个用户环境下单独执行，不能靠环境变量继承
最常被跳过的一步是验证真实路径——composer config --global cache-dir 输出的只是配置项，composer diag 才反映实际行为。一旦看到 Cache is not working due to permissions，说明路径存在但不可写，Composer 已悄悄退回到默认位置，而你还在检查配置文件有没有写错逗号。
