ThinkPHP 5.0/5.1 项目不能直接升级到 6.x，必须先升至 5.1.40+（LTS），再迁移到 6.3+；因 TP6 是架构级重构，涉及容器、路由、中间件、数据库构建器、模板引擎等全面不兼容变更，直接升级将导致大量类未找到、方法不存在及路由 404 错误。
ThinkPHP 5.0/5.1 项目不能直接升到 6.x，必须分阶段过渡；最稳妥路径是先升到 5.1.40+（LTS），再迁移到 6.3+，跳过 6.0–6.2 这些早期非长期支持版本。
为什么不能从 5.0 直接跳到 6.x
TP6 是一次架构级重构：核心容器从单例改为依赖注入容器、路由完全重写、中间件机制不兼容、数据库查询构建器返回对象类型变更（Query vs Builder）、模板引擎默认切换为 think-template 而非 Think。直接升级会导致大量 Class not found、Call to undefined method 和路由 404。
- TP5.0 的
Db::name('user')->where('id', 1)->find()在 TP6 返回think\Model实例，但模型类定义方式、验证逻辑、事件钩子全部不兼容 - TP5 的
config('database')是数组，TP6 中config('database')默认返回think\Config对象，直接取值会报错 - TP5 的
Loader::import()、Vendor()等函数在 TP6 中已移除，但旧扩展或私有类可能仍在调用
第一阶段：5.0 → 5.1.40+（关键兼容垫层）
TP5.1 是 5.x 系列最后一个 LTS 版本，它提前引入了部分 TP6 的设计思路（如容器绑定、中间件注册方式），同时保留了绝大多数 5.0 的 API 行为，是理想的“缓冲带”。
- 确认当前项目无硬编码调用
think\Loader或手动 require 类文件 —— 这类代码在 5.1 中仍能运行，但必须清理掉才能进下一阶段 - 将
composer.json中的"topthink/framework": "^5.0"改为"topthink/framework": "5.1.40"，然后执行composer update topthink/framework - 重点检查
app.php配置：TP5.1 开始要求default_return_type显式声明，且trace配置结构变化，否则启动时报Undefined index: type - 运行
php think optimize:autoload重建自动加载映射，避免因命名空间变更导致的类找不到问题
第二阶段：5.1.40+ → 6.3+（接口迁移与重构）
这步不是 composer update 一下就行，而是要逐模块替换调用方式，尤其注意请求生命周期中“中间件→控制器→视图”的链路断裂点。
立即学习“PHP免费学习笔记（深入）”；
- 入口文件
public/index.php必须替换为 TP6 标准版本，旧版中define('APP_PATH', ...)+require方式不再被识别 - 控制器方法签名强制变更：
index(Request $request)替代index()，所有获取参数必须通过$request->param()、$request->post()，input()函数仅限模板内使用 - 数据库操作建议逐步改用
Db::table('user')而非Db::name('user')，后者在 TP6 中虽保留但行为已不同（比如字段缓存策略） - 模板中禁用
{:function()}写法，改用{:helper_function()}或自定义模板函数，否则渲染时报Undefined function
容易被忽略的三个硬伤点
很多团队卡在这三处超过一周：一是日志驱动配置项名从 type 变成 driver，二是命令行指令 php think 的参数解析逻辑变更（--force 不再全局生效），三是多应用模式下 app/middleware.php 的注册方式彻底废弃，必须改用 app/middleware.php 中的 middleware 数组 + app/middleware/ 目录结构。
真正难的不是语法替换，而是旧项目里那些没写文档的“魔法调用”——比如某个中间件里直接 $_SERVER['HTTP_X_TOKEN'] 取头信息，TP6 的 Request 对象默认不代理原始超全局变量，这类细节得靠日志和断点一个个捞出来。
