遇到 ThinkPHP 旧项目升级后的 Composer 依赖冲突，单纯清理缓存往往不够。核心在于排查 composer.json 约束与目标版本的兼容性，必要时使用诊断工具定位冲突包。

依赖冲突诊断工具

不要盲目清理文件，先使用 Composer 自带工具定位哪个包导致了冲突。

1. 检查包版本限制原因

如果安装失败，使用 composer why-not 查看为何不能安装特定版本。例如检查为何不能安装 ThinkPHP 6.0：

composer why-not topthink/framework ^6.0

输出会显示哪个依赖包限制了版本升级，例如某个第三方插件要求 topthink/framework ^5.1，这就是冲突根源。

2. 查看完整依赖树

使用 composer show 查看当前已安装的包及其版本，辅助判断是否存在遗留的旧版本依赖。

分步处理流程

第一步：备份当前项目

在执行任何清理操作前，务必对整个项目目录进行备份，或者确保代码已提交到版本控制系统。依赖更新不可逆，一旦出错需要回滚。

git add .
git commit -m "backup before upgrade"

第二步：检查 PHP 版本

在终端执行 php -v 查看当前环境版本。对照目标 ThinkPHP 版本的官方要求，例如 ThinkPHP 6.0 要求 PHP 7.2.5 以上。如果版本过低，需要先升级服务器 PHP 环境，不要试图通过忽略平台要求来强制安装。

第三步：调整 composer.json 约束

打开 composer.json，检查 require 部分。如果是升级到 ThinkPHP 6，确保 topthink/framework 的版本约束是 ^6.0 或更高。如果有冲突的第三方插件，暂时注释掉或调整版本约束。

"require": {
    "topthink/framework": "^6.0",
    "topthink/think-orm": "^2.0"
}

第四步：清理锁文件和依赖目录

确认配置修改无误后，删除项目根目录下的 vendor 文件夹和 composer.lock 文件。这两个文件记录了旧的依赖状态，删除后 Composer 会根据新的 composer.json 重新计算依赖树。

rm -rf vendor
rm composer.lock

第五步：重新安装依赖

执行更新命令。如果网络较慢，可以切换国内镜像源。遇到脚本执行错误时，可以临时跳过脚本执行。

composer update `--no-scripts`

如果特定包冲突，可以尝试单独指定版本安装：

composer require topthink/framework:^6.0

怎么验证是否生效

依赖安装完成后，不要直接上线，先在本地或测试环境验证。

1. 检查框架版本

在项目根目录执行以下命令，确认 ThinkPHP 版本已更新到预期版本：

php think -v

2. 检查基础路由

启动内置服务器或访问 Web 入口，查看首页是否能正常加载，有没有报 500 错误。重点观察日志文件 runtime/log 下是否有依赖缺失类的报错。

3. 分析报错日志

如果出现 Class not found 或 Fatal Error，查看报错文件路径。如果是 vendor 内的文件，可能是依赖版本不对；如果是应用目录文件，可能是命名空间未更新。

常见坑与排查

1. 命名空间未更新

ThinkPHP 6 的命名空间与 5.x 有较大差异。如果代码中硬编码了旧的路径或类名，即使依赖安装成功，运行时也会报错。需要全局搜索旧命名空间并替换。

2. 配置文件格式变化

新版本可能不再支持旧版的配置文件格式。升级后需检查 config 目录下的文件是否符合新规范，特别是数据库和缓存配置。

3. 扩展兼容性问题

某些第三方扩展可能尚未适配新版本的 ThinkPHP 或 PHP。如果 composer update 卡住或报错，尝试暂时移除该扩展，确认核心框架升级成功后再单独处理扩展。

4. 权限问题

清理 vendor 后重新安装，确保运行 Composer 的用户对项目目录有写入权限，否则会导致文件生成失败，引发后续加载错误。