ThinkPHP文件迁移需分步适配：确认源目标版本、按TP5.1→TP6.0→TP8.0分阶段升级；更新控制器/模型语法、验证器、配置键名、路由中间件、迁移文件格式及扩展版本，并清空runtime目录。
ThinkPHP 文件迁移不是简单复制粘贴，核心在于结构适配、语法升级、配置重写和扩展替换。直接把 TP5 或 TP6 的文件扔进 TP8 项目里，大概率会报错、功能失效甚至引发安全问题。
迁移前必须确认的几件事
- 明确源版本（比如 TP5.1）和目标版本（比如 TP8.0）
- 查看官方《升级指南》中“废弃项”和“变更项”列表（TP5→TP6→TP7→TP8 是分阶段演进）
- 不要跨太多大版本直跳（如 TP5.0 → TP8.0），建议按 TP5.1 → TP6.0 → TP8.0 分步走，每步验证核心流程
关键文件迁移要点
控制器与模型文件
- TP5 中
$this->assign()在 TP8 仍可用，但推荐改用view()->assign()或模板引擎原生语法 - 模型类若继承
\think\Model，TP8 需确认是否已安装webman/think-orm（Webman 场景）或仍用topthink/think-orm（FPM 场景）；类名空间保持app\model\User即可，但内部方法如save()的参数规则有调整（例如allowField默认关闭） - 删除所有
$validate数组写法，迁移到独立验证器类（app\validate\User），并在控制器中显式调用Validate::make()或实例化检查
配置文件（config/ 目录下）
- TP5 的
database.php返回纯数组，TP8 要求键名严格匹配（如'hostname' => '127.0.0.1'，不能写成'host'） -
app.php中'default_module'在 TP8 已移除，路由由config/route.php统一管理 -
.env文件在 TP6+ 默认启用，但数据库配置需显式在config/database.php中通过Env::get('database.')加载，不能只靠.env
迁移文件（database/migrations/）
立即学习“PHP免费学习笔记（深入）”；
- TP5.x 用
topthink/think-migration:2.x，TP6/TP7 用^4.0，TP8 必须用^4.0（不是^3.0） - 文件路径必须是
database/migrations/（注意是 migrations，不是 migrate） - 类名必须为
YYYYMMDDHHIISS_DescribeTable格式，例如20240921153000_CreateUsersTable.php -
up()和down()方法里禁用模型操作（如UserModel::create()），只用$this->table()->create()等迁移专用链式方法
中间件与路由
- TP5 的
application/middleware.php全局中间件写法在 TP8 失效，需改为app/middleware/下的类文件 +config/middleware.php中注册 - 路由全部收口到
config/route.php，不再支持控制器内定义；Route::get('user', 'index')写法保留，但闭包路由需显式返回response()实例
容易忽略但致命的细节
-
runtime/目录必须清空，否则旧缓存可能干扰新版本自动加载 - 所有自定义函数、助手函数（如
p()、dump()）需检查是否被移除或重命名（TP8 推荐用var_dump()或think\facade\Debug::dump()） - TP5 的
vendor/topthink/think-captcha等扩展，在 TP8 中需换为topthink/think-captcha的 3.x 版本，并注意验证码存储方式是否从 session 切到 cache
不复杂但容易忽略
