元数据损坏导致vendor与installed.json不一致，引发“Package not installed”或“Class not found”；应验证installed.json合法性、匹配install-path，单包问题手动清理后重装，大面积失效则清空vendor并用--no-cache重装。
Composer元数据损坏或还原失败，通常不是“重装就能好”的问题——它直接卡在依赖解析起点，composer install 甚至都跑不起来。核心矛盾在于 vendor/composer/installed.json、composer.lock 和本地包实际状态三者不一致，而 Composer 不会自动修复这种不一致。
composer install 报错 “Package is not installed” 或 “Class not found” 却有 vendor 目录
这是最典型的元数据失配现象：文件物理存在，但 installed.json 没记录，或记录了错误的安装路径/版本。Composer 的自动加载器（vendor/autoload.php）只认 installed.json 里的注册信息，不扫描文件系统。
- 先确认
vendor/composer/installed.json是否可读、JSON 格式合法（用jq . vendor/composer/installed.json快速验证） - 检查该文件中对应包的
name、version、install-path字段是否与vendor/xxx/yyy实际路径匹配 - 若只是单个包出错，可手动删掉
vendor/xxx/yyy及其在installed.json中的条目，再运行composer require xxx/yyy - 若大面积失效，不要手修
installed.json，应清空vendor并重跑composer install --no-cache
从备份还原 composer.lock 后 install 卡在 “Resolving dependencies”
这说明 composer.lock 里记录的哈希或版本约束，在当前网络或仓库镜像下已无法解析。尤其常见于跨 PHP 版本还原（比如 PHP 8.2 备份的 lock 文件在 PHP 8.5 下还原），或私有包源地址变更后未同步更新 repositories 配置。
- 运行
composer install -v查看卡在哪一个包，再用composer show xxx/yyy确认该包是否在当前源中可访问 - 对比还原前后的
composer.json，检查repositories块是否缺失或 URL 写死为内网地址 - 如果锁文件来自旧环境且不可信，直接删掉
composer.lock，改用composer update --lock重新生成（注意：这会升级所有满足约束的包） - PHP 版本不一致时，
composer install会跳过不兼容的包，但不会报错提示——加--ignore-platform-reqs是临时绕过手段，非长期方案
还原 vendor 目录后 autoload.php 不生效
vendor/autoload.php 本身是生成文件，它依赖 installed.json 和 classmap.php 等中间产物。直接复制整个 vendor 目录过去，大概率导致 PSR-4 映射失效或类找不到，因为路径硬编码进了生成逻辑里。
- 绝对不要把
vendor当作可移植资产备份——它和当前项目根目录、PHP 版本、Composer 版本强绑定 - 正确做法是只备份
composer.json和composer.lock，还原时用它们重建vendor - 若必须迁移已安装的 vendor（如离线环境），需同时拷贝
vendor/composer/全部内容，并确保目标机上composer dump-autoload能成功执行 - 遇到
Class XXX not found但命名空间路径明显正确时，先运行composer dump-autoload -o强制刷新优化后的 classmap
真正容易被忽略的是时间差：composer.lock 里每个包的 dist.shasum 是下载时计算的，一旦远程包被覆盖（比如 maintainer 重推同版本 tag），还原就必然失败——这不是你操作错了，是生态本身就不支持“确定性回滚”。遇到这种情况，只能接受新哈希，或切换到更稳定的镜像源归档服务。
