composer clear-cache 仅清理 ~/.composer/cache/ 下的下载包和元数据，不影响 vendor/ 和 composer.lock；适用于网络错误、元数据过期或镜像切换后仍走旧源等场景，但会拖慢首次安装。
Composer 的缓存不会自动清理，长期不处理会导致 composer install 拉取旧包、校验失败或下载缓慢——直接运行 composer clear-cache 就能解决，但得知道它清什么、不清什么、以及什么时候不该清。
缓存位置和内容：不是所有“缓存”都归 clear-cache 管
Composer 实际维护两类缓存：
-
~/.composer/cache/（linux/macos）或%APPDATA%Composercache（windows）：这是clear-cache唯一操作的目标，含已下载的 zip 包、dist 包元数据、vendor 包解压快照 - 项目级
vendor/和composer.lock：不受影响，clear-cache不碰它们，也不会重装依赖
常见误解是“清了缓存就能绕过 composer.lock”，其实不行——锁文件仍会强制安装指定版本，缓存只影响下载源和校验速度。
什么时候必须用 composer clear-cache
典型触发场景：
- 反复出现
file could not be downloaded: failed to open stream: Connection refused，但网络正常——说明缓存里存了损坏的包头或断连残留 - 执行
composer update时卡在 “Loading composer repositories”，且composer config -g repo.packagist.org显示镜像配置正确——大概率是本地缓存的 repo 元数据过期或错乱 - 切换了国内镜像（如从 packagist.org 换到阿里云），但
composer require仍走海外源——缓存里还存着旧的 repo 响应结果
clear-cache 的副作用和规避方式
命令本身安全，但有两点容易被忽略：
- 清除后首次
composer install或update会明显变慢，因为所有 dist 包要重新下载（尤其大包如laravel/framework） - 如果磁盘空间紧张，别只清缓存——先检查
~/.composer/cache/files/是否堆积了大量旧版本 zip（du -sh ~/.composer/cache/files/* | sort -hr | head -n 5），手动删掉不用的目录更有效 - CI/CD 流水线中慎用：缓存本是用来加速的，除非明确遇到校验失败，否则加
composer clear-cache只会拖慢构建
替代方案：比清缓存更精准的操作
多数问题其实不需要全量清空：
- 仅刷新元数据：运行
composer clear-cache && composer update --lock，避免重装 vendor - 跳过 dist 缓存（强制从 source 安装）：
composer install --prefer-source，适合调试 fork 后的包 - 临时禁用缓存（调试用）：
COMPOSER_CACHE_DIR=/dev/NULL composer install，Linux/macOS 下生效
真正麻烦的是缓存和 lock 文件、镜像源、PHP 版本约束三者混在一起出问题——这时候光清缓存没用，得看 composer why-not vendor/package:version 找冲突根因。