composer clear-cache 只清理 ~/.composer/cache/ 下的 repo/ 和 files/ 缓存，不影响 vendor/、composer.lock 和已安装依赖；它适用于缓存损坏、元数据未更新或镜像源切换后不同步等情况。
composer clear-cache 命令到底清的是什么
它只清理 Composer 自己维护的包下载缓存（~/.composer/cache/ 下的 repo/ 和 files/），不碰 vendor/、不删 composer.lock、也不影响已安装的依赖。很多人误以为执行后会重装包，其实不会——composer install 依然照常读 lock 文件、复用 vendor。
什么时候必须用 clear-cache
遇到这些情况才值得跑：
– composer require 或 update 报错，提示 “Could not parse version constraint” 或 “Repository could not be parsed”，但换网络或换源后正常 → 可能是 repo 缓存损坏
– 明明 Packagist 上已发布新版本（比如 v2.1.0），但 composer show vendor/package 仍显示旧版，且 composer update vendor/package 不生效 → 缓存没刷新元数据
– 切换镜像源（如从 packagist.org 改为阿里云）后，composer search 结果仍是旧的 → 缓存未同步新源结构
clear-cache 的常见误操作和副作用
以下做法反而会让问题更难排查：
– 在 CI 环境里无条件加 composer clear-cache → 拖慢构建，且掩盖真实问题（比如网络超时或权限错误）
– 执行前没确认当前用户：如果用 sudo composer clear-cache，缓存路径会变成 /root/.composer/cache/，而普通用户后续命令仍读自己的缓存，等于白清
– 以为清缓存能解决 autoload 失败 → 实际上 composer dump-autoload 才管这个，缓存和 autoloader 完全无关
– 清完立刻 composer install 却报 404 → 很可能镜像源配置没生效，缓存清了，但源还是不可达，该下不下来的包照样下不了
比 clear-cache 更有效的替代方案
多数时候，直接清缓存不是最优解：
– 想强制更新某包元数据？用 composer update vendor/package --no-cache，跳过缓存读取，但保留其他包缓存
– 怀疑缓存损坏但不确定？先看缓存路径：composer config --global cache-dir，然后手动 ls -l 看 repo/ 下最近修改时间是否异常早
– 镜像源失效？优先检查 composer config --global repo.packagist.org 是否指向有效地址，而不是一上来就清缓存
– CI 中频繁失败？把 composer clear-cache 换成 rm -rf ~/.composer/cache/ 并确保非 root 用户执行，避免权限残留
缓存本身不是敌人，它是 Composer 加速的关键机制；真正麻烦的是缓存和实际源状态不一致，而这种不一致往往藏在镜像配置、网络策略或用户权限里，不在缓存文件本身。