ThinkPHP项目迁移需完成环境适配、配置重置和状态清理三步。须备份代码与数据库，确认PHP≥8.0及必要扩展，导出数据库时加特定参数；Web根目录必须指向public，启用伪静态；删除旧.env和runtime目录，通过服务器变量注入数据库配置；使用think-migration需手动安装并注册命令。
ThinkPHP项目迁移不是简单复制文件，核心在于环境适配、配置重置和状态清理三件事。跳过任意一环，轻则白屏报错，重则数据错乱或路由失效。
准备阶段：备份与环境确认
迁移前必须做两件事：全量备份代码和数据库；确认新服务器 PHP 版本（TP6.1+ 要求 ≥8.0）、关键扩展（openssl、mbstring、pdo_mysql、fileinfo）已启用，且 mbstring.func_overload = 0。用 php -v 和 php -m 核对，别只看宝塔面板显示。
- 数据库导出加
--no-definer --skip-triggers --single-transaction，避免 DEFINER 权限错误 - 检查旧项目是否用了视图或存储过程，如有需额外加
--routines - 把 .env 文件单独存好，别直接打包进 Git，上线后它必须被移除或重写
部署阶段：目录结构与入口设置
ThinkPHP 6 默认要求 Web 根目录指向 public 目录，不是项目根目录。宝塔或 Nginx 配置里若仍设在顶层，所有请求都绕过入口文件，必然 404。
- 宝塔操作：网站 → 根目录 → 改为
/www/wwwroot/your-site/public - Nginx 必须启用伪静态，并选择 ThinkPHP 规则；Apache 需确保
.htaccess在 public 下且mod_rewrite已开启 - 上传后立刻执行
chmod 644 .env，权限不能是 755，否则可能被直接访问
配置阶段：数据库与运行时重置
数据库连接不生效，90% 是因为配置没更新或缓存没清。线上环境严禁保留本地 .env，更不能把它提交进代码库。
立即学习“PHP免费学习笔记（深入）”；
- 删掉项目根目录下的 .env，改用宝塔「网站配置文件」在
location /块中透传变量，如set $env_db_host "192.168.10.100"; - 修改
config/database.php，读取方式改为$_SERVER['HTTP_ENV_DB_HOST'] ?? '127.0.0.1' - 迁移后必须删除整个
runtime/目录——里面缓存的数据库地址、路由映射、模板编译全是旧环境的
验证阶段：命令与迁移同步
如果要用数据库迁移功能，它不是默认开启的，必须手动装包、注册命令、初始化状态表。否则 php think migrate:run 会直接报 “Command not defined”。
- 执行
composer require topthink/think-migration:^3.0（TP6.1+ 必须用 ^3.0） - 检查
config/console.php的'commands'数组是否含'\think\migration\Command::class' - 运行
php think list，确认输出里有migrate:install和migrate:run - 首次运行前先
php think migrate:install创建think_migration状态表
