缓存目录权限错乱、ZIP损坏、metadata滞后或目录不存在均导致clear-cache失效；需分别修复权限、删除坏ZIP、清空repo缓存或重建目录并赋权。
缓存目录权限错乱导致 clear-cache 无效
运行 composer clear-cache 后仍复用旧包、报错不消失，大概率不是缓存内容损坏，而是缓存目录本身权限异常——Composer 写入失败但静默跳过，后续 install/update 仍读取残留文件。
- Linux/macOS：先查路径
composer config --global cache-dir（通常是~/.composer/cache），再执行：rm -rf ~/.composer/cache && mkdir -p ~/.composer/cache && chmod 755 ~/.composer/cache
- Windows：路径在
%APPDATA%\Composer\Cache，需右键该目录 → 属性 → 安全 → 编辑 → 为当前用户勾选“完全控制” - WSL 用户必须避开
/mnt/c/路径，改用~/projects/等原生 Linux 路径，否则chmod和chown是假动作
ZIP 文件结构损坏引发 Extracting 失败
报 Failed to extract 或 Corrupted zip file，不是网络问题，而是 ~/.composer/cache/files/ 下某个 ZIP 文件下载中断或磁盘写异常导致结构损坏。Composer 不校验 ZIP 完整性，只比对哈希值，可能直接复用坏包。
- 盯住
composer install -v输出末尾，找到类似Extracting vendor/symfony/console的行，提取包名（如symfony/console） - 进缓存
files/目录，模糊搜索并仅删对应 ZIP：ls -l *symfony*console*.zip（Linux/macOS）
PowerShell 中：Get-ChildItem "$env:APPDATA\Composer\Cache\Files" -Recurse -Filter "*console*.zip" - 别碰
repo/和vcs/目录——它们不参与解压；删 ZIP 后若还报错，说明composer.lock里硬编码的dist.sha256值与新内容不匹配，必须同步删掉vendor/和composer.lock
metadata 缓存滞后导致 update 拉不到新版
composer update 显示 “nothing to install or update”，但 Packagist 上已有新版本，大概率是 metadata 缓存未刷新——composer clear-cache 不强制拉取 packages.json，而 Composer 会复用 ~/.composer/cache/repo/https---packagist.org/ 下旧的 provider 映射和索引文件。
- 必须手动删整个 repo 子目录：
rm -rf $(composer config --global cache-dir)/repo/https---packagist.org/
- 同时删掉
vendor/composer/installed.json（当前安装快照）和composer.lock（版本锁定） - 再跑
composer update，它才会重新请求完整元数据
缓存目录根本不存在时 clear-cache 直接报错
报 cache directory does not exist，不是权限问题，就是路径压根没建——常见于重装系统后未初始化 Composer，或误设了非法 cache-dir 路径。
- 先确认：
composer config --global cache-dir查出路径，再立刻验证是否存在：
Linux/macOS：ls -ld $(composer config --global cache-dir)
Windows PowerShell：Test-Path "$env:APPDATA\Roaming\Composer\Cache" - 重建目录并确保归属正确：
Linux/macOS：mkdir -p $(composer config --global cache-dir) && chown -R $USER:$USER $(composer config --global cache-dir)
Windows（管理员 PowerShell）：mkdir "$env:APPDATA\Roaming\Composer\Cache"; icacls "$env:APPDATA\Roaming\Composer\Cache" /grant "$env:USERNAME:(OI)(CI)F" /t
- 检查环境变量干扰：
$COMPOSER_CACHE_DIR（Linux/macOS）或$env:COMPOSER_CACHE_DIR（PowerShell）优先级高于全局配置，若指向不存在路径，Composer 可能卡在检查阶段；临时清除它再试
最易被忽略的是：composer config --global cache-dir 只改配置，不自动创建目录；而 composer clear-cache 在目录不存在时会直接报错退出，不会帮你兜底。必须手动建 + 权限对齐，一步都不能少。
