必须经TP6过渡：TP5.1→TP8.0是重写级迁移，需5.1→6.0→8.0分步升级，TP6作为“语义桥”暴露返回格式、路由注解、命名空间等兼容问题，跳过将导致路由失效、配置不加载、类找不到等静默故障。
不能跳版本是对的——TP5.1 直升 TP8.0 是重写级迁移，不是升级。唯一可行路径是 5.1 → 6.0 → 8.0，中间必须经过 TP6 过渡，否则路由失效、配置不加载、类找不到等静默故障会大量出现。
为什么必须走 TP6 这一步？
TP5.1 和 TP8.0 的底层断裂点太多，TP6 是官方设计的“语义桥”：
-
config/app.php中default_return_type在 TP5.1 是html，TP6 改为json，你能在 TP6 阶段提前暴露接口返回格式变更问题，而不是等到 TP8 才发现前端全乱码 - TP5.1 的注释路由（
/** @route GET /api/user */）在 TP6 已被弃用，但 TP6 还保留兼容层提示；TP8 则完全移除，只支持#[Route]Attribute，TP6 阶段可批量替换并验证 - TP5.1 的
app/目录结构（如app/index/controller）在 TP6 开始强制要求命名空间与路径严格对应，TP6 会报错提醒你修正use和namespace，TP8 则直接不扫描
TP5.1 → TP6 升级时最常卡住的三件事
这三步不做，composer update 后大概率白屏或 404：
- 入口文件
public/index.php必须替换为 TP6 标准引导：删掉旧的require链，改用(new \think\App())->run()->send() -
application/目录要整体重命名为app/，且所有控制器、模型类的namespace必须从app\index\controller改为app\index\controller（注意：TP6 要求命名空间与目录名完全一致，大小写敏感） - 运行
php think optimize:config生成配置缓存，并确认runtime/已清空——TP6 对缓存结构更敏感，残留 TP5.1 缓存会导致config('database')返回空数组
TP6 → TP8 升级的关键动作清单
TP6 到 TP8 不再是结构迁移，而是语法和契约升级，重点在“替换”而非“重构”：
立即学习“PHP免费学习笔记（深入）”；
- 全局助手函数全部失效：
input()→$this->request->param()，cookie()→$this->cookie->get()，config()→Config::get()（别忘了use think\facade\Config） -
Db::name('user')必须改为Db::table('user')或模型调用（如User::find(1)），name()方法在 TP8 中已彻底删除 - 中间件注册必须传完整类名：
->middleware('check')→->middleware(\app\middleware\Check::class)，字符串别名方式 TP8 不识别 - 检查
config/annotation.php，确保'scan' => ['app\controller']存在；若有多模块（如app\admin），必须显式加入'app\admin\controller'，TP8 不再自动扫描子命名空间
最后一步：别信“缓存清了就行”
升级后出问题，90% 是因为没清干净或清错了地方：
- 删掉
vendor/、composer.lock、runtime/三个目录，缺一不可——composer.lock残留会导致 Composer 拉取 TP5.1 兼容包，表面装成功，实际运行报Class 'think\Db'找不到 - 执行
composer install --no-dev后，必须补一句composer dump-autoload -o，TP8 对自动加载性能更敏感，未优化会导致首次请求慢 2–3 秒 - 确认 CLI 和 Web SAPI 使用同一 PHP 版本（
php -v和phpinfo()输出一致），尤其注意mbstring、fileinfo、pdo_mysql是否都启用——TP8 启动阶段就校验扩展，缺一个就直接终止
真正难的不是代码怎么改，而是你得在 TP6 阶段就接受“它已经不是你熟悉的 TP5.1”——比如 Request 对象不再全局可调，Cookie 组件不再自动初始化，这些“理所当然”的消失，才是小步升级中最容易忽略的断点。
