根本原因是composer读取了缓存中过期的packages.json快照，误判远程包可用性，导致按错误元数据安装；必须先执行composer clear-cache并验证缓存目录为空，再运行composer install。
缓存残留导致 composer install 装错版本
根本原因不是 lock 文件没生效，而是 Composer 读了旧缓存里的 packages.json 快照，误判远程包可用性，结果按“过期元数据”安装了错误版本。常见现象：git checkout 回退到旧 commit、composer.lock 恢复正确、vendor 删除干净，但 composer install 后 vendor/ 里仍是新版本代码。
- 先执行
composer clear-cache—— 这不是可选步骤，是硬性前置动作 - 验证是否清空：
ls -la ~/.composer/cache/（Linux/macOS）或dir %APPDATA%\Composer\Cache\（Windows），目录应为空或只剩空子目录 - 若仍有内容，可能是 PhpStorm 或其他 IDE 锁住缓存目录；可临时切换缓存路径再清：
composer config -g cache-dir /tmp/composer-cache-empty && composer clear-cache - 清完后立刻跑
composer install，别穿插composer update或require，避免再次污染缓存
项目级 repositories 配置覆盖全局源
多环境部署时，CI/CD 流水线常在不同分支写入不同镜像源（如测试用腾讯云、生产用官方源），但 composer.json 中的 "repositories" 块优先级最高，会直接屏蔽 composer config -g repo.packagist 的设置。结果就是：本地配置看似回滚成功，实际请求仍发往旧镜像。
- 检查项目级是否污染：
composer config repo.packagist（不加-g），输出非https://packagist.org就说明被覆盖了 - 快速定位：
grep -A 5 '"repositories"' composer.json（Linux/macOS），或直接打开文件搜索"repositories" - 清理方式：删掉整个
"repositories": [...]块；若需临时保留私有源，改用composer config repo.packagist composer https://packagist.org显式覆盖 - 验证真实请求地址：
composer require monolog/monolog --no-install -vvv，观察日志中Downloading https://...的 URL 是否为https://repo.packagist.org/packages.json
opcache 和 autoload 缓存干扰降级验证
降级完成后运行 composer show vendor/package 显示旧版本，但实际代码行为仍是新的——这大概率不是 Composer 没装对，而是 PHP 还在执行旧字节码或类映射。
- opcache 必须重置：
opcache_reset()（代码中调用）或重启 PHP-FPM：sudo systemctl restart php8.2-fpm - autoload 缓存可能残留：
composer dump-autoload --optimize会生成 classmap 缓存，降级后旧类名可能还在映射里；执行composer dump-autoload（不带--optimize）重建映射 - 检查
vendor/bin/下二进制文件是否残留旧版（如phpunit、phpcs），它们可能被 PATH 优先调用，手动删掉再composer install重建 - 某些包的
post-install-cmd（如生成配置、编译前端资源）不会因composer install自动重放，需手动触发：composer run-script post-install-cmd
跨主版本降级失败却报错模糊
想把 guzzlehttp/guzzle 从 ^8.0 降到 7.4.5，执行 composer require guzzlehttp/guzzle:7.4.5 --with-all-dependencies 却只报 Your requirements could not be resolved，没说谁拦的——这是 Composer 依赖解析器在回溯失败路径，但默认不展开细节。
- 必须加
--dry-run -v查根源：composer require guzzlehttp/guzzle:7.4.5 --with-all-dependencies --dry-run -v - 关键线索在日志里反复出现的
Trying guzzlehttp/guzzle 7.4.5 → Reverting → Backtracking，说明某条依赖链上存在硬性约束冲突 - 用
composer why-not guzzlehttp/guzzle:7.4.5直接列出所有封杀该版本的包及其require字段 - 再查该旧版本实际依赖：
composer show guzzlehttp/guzzle 7.4.5，确认它要求的psr/http-client版本是否与当前环境兼容 - 若问题出在
config.platform.php（如设为"8.2"），而7.4.5只支持^7.4 || ^8.0，临时删掉该配置再试
composer clear-cache 不够，得配合项目级 repositories 清理、PHP 级 opcache 重置、autoload 重建，才算真正切断旧状态残留。
