>适用版本：ThinkPHP5.x/6.x/8.x（配置项名称略有差异，文中会标注）
>关键词：ThinkPHP迁移、配置修改、数据库迁移、伪静态、缓存清理

一、迁移前准备（决定成败的80%）

ThinkPHP迁移失败，绝大多数不是代码问题，而是环境差异和配置残留。动手前请先完成以下清单：

1.环境信息盘点：记录源服务器PHP版本、扩展（`pdo_mysql`、`mbstring`、`fileinfo`、`gd`/`imagick`、`redis`）、Web服务器（Nginx/Apache）、MySQL版本、操作系统。
2.全站打包：代码+`public/uploads`（上传目录）+`runtime`可排除+数据库SQL导出（含视图、触发器）。
3.备份校验：SQL文件本地导入一次，确认无报错、表数量一致。
4.域名/证书：确认新域名、SSL证书、备案状态（国内服务器）。
5.迁移窗口：选择低峰期，提前在旧站挂“维护中”提示或设置只读。

>⚠️数据对比：迁移前务必记录表数量、总记录数、上传文件数量与体积，迁移后逐项核对。这是排查“数据丢失”最直接的手段。

二、核心：ThinkPHP迁移需要改哪些配置

以下按“必改→建议改→视情况改”分级列出。

2.1环境变量文件`.env`（TP5.1+/6+/8首选）

ThinkPHP6/8推荐通过`.env`管理，优先级高于`config/.php`：

“`ini
APP_DEBUG=false
APP_TRACE=false

[APP]
DEFAULT_TIMEZONE=Asia/Shanghai

[DATABASE]
TYPE=mysql
HOSTNAME=新数据库地址
DATABASE=数据库名
USERNAME=数据库用户
PASSWORD=数据库密码
HOSTPORT=3306
CHARSET=utf8mb4
PREFIX=tp_

[REDIS]
HOST=127.0.0.1
PORT=6379
PASSWORD=
“`

2.2数据库配置

-文件：`config/database.php`（TP6/8）或`application/database.php`（TP5）
-必改：`hostname`、`database`、`username`、`password`、`hostport`
-注意：`charset`统一`utf8mb4`；`prefix`若表前缀变化必须同步；`params`中的`PDO::ATTR_EMULATE_PREPARES`保持默认。

2.3应用与入口配置

-`config/app.php`：`app_debug`（生产务必`false`）、`default_timezone`（`Asia/Shanghai`）、`app_host`/`domain`（若代码中用到绝对URL）。
-`public/index.php`：确认`define(‘APP_PATH’,…)`、入口文件路径正确。
-入口文件是否在public下：TP6/8必须将Web根目录指向`public/`，若沿用旧习惯指向项目根，需在根目录补`index.php`或调整Nginx`root`。

2.4URL与路由配置

-`config/route.php`：`url_route_must`、`url_html_suffix`、`pathinfo_depr`保持与旧站一致，否则站内链接全部404。
-伪静态规则必须迁移：Nginx为例：

“`nginx
location/{
if(!-e$request_filename){
rewrite^(.)$/index.php?s=$1last;
}
}
“`

Apache则确认`.htaccess`与`mod_rewrite`已启用。

2.5缓存与Session

-`config/cache.php`：缓存驱动（file/redis/memcache）、`prefix`、`expire`。迁移到新机若Redis地址变化必须改。
-`config/session.php`：`type`、`store`、`prefix`。若用Redis存Session，迁移后旧Session失效属正常。
-务必删除`runtime/`下所有缓存（`runtime/cache`、`runtime/temp`、`runtime/log`），否则可能出现旧域名跳转、旧配置生效。

2.6日志与上传路径

-`config/log.php`：`path`、`level`（生产建议`error`以上）。
-`config/filesystem.php`（TP6/8文件上传）：`root`路径如`public/uploads`，迁移后确认目录存在且`www`用户可写。

2.7其他易漏项

-`config/database.php`里的`deploy`（读写分离）——若新机单库需关闭。
-代码中硬编码的域名/IP：搜索`http://`、`https://`、旧服务器IP、`127.0.0.1`，全部替换。
-`.htaccess`/Nginx里的`root`路径。
-定时任务crontab、队列worker（`phpthinkqueue:work`）需在新机重建。

三、迁移后数据对比与校验

校验项 旧服务器 新服务器 是否一致 说明
PHP版本 7.4.33 8.1.x ✅/❌ 小版本升级需回归测试
MySQL版本 5.7.38 8.0.x ✅/❌ 8.0注意sql_mode、caching_sha2
数据库表数量 42 42 含视图/触发器
主表记录数（如tp_user） 158,320 158,320 SQL校验COUNT()
上传文件数量 12,458 12,458 find . -type f | wc -l
uploads体积 8.7GB 8.7GB du -sh
首页响应时间 320ms 280ms 压测对比
伪静态是否生效 是 是 随机打开10个内页
缓存/日志目录 有 已清理 runtime删除后自动重建
定时任务 3个 3个 crontab -l

>建议做法：用脚本对新旧库分别执行`SELECTtable_name,table_rowsFROMinformation_schema.tables`，导出CSV比对；文件用`rsync–dry-run`核对差异。

四、迁移执行流程（推荐顺序）

1.新服务器装好环境，版本尽量与旧机一致。
2.上传代码→修改`.env`/数据库配置→导入SQL。
3.配置Nginx`root`指向`public/`，加伪静态规则。
4.目录权限：`runtime`、`public/uploads`给`www`读写（`chown-Rwww:www`）。
5.删除`runtime/`缓存。
6.访问首页→后台→关键功能（登录、下单、上传）逐个测试。
7.全站随机抽检20个内页，确认路由和伪静态正常。
8.关闭`app_debug`，观察`runtime/log`是否有报错。
9.DNS切换，旧站保留48小时可回滚。

五、FAQ问答

Q1：迁移后首页正常，但内页全部404，是什么原因？
A：99%是伪静态规则未生效或Web根目录没指向`public/`。检查Nginx是否配置`try_files`/`rewrite`、`root`是否指向TP6/8的`public`目录，并确认`config/route.php`的`url_html_suffix`与旧站一致。

Q2：数据库导入后中文乱码怎么办？
A：确认三处编码一致：SQL导出时用`–default-character-set=utf8mb4`；`config/database.php`的`charset`为`utf8mb4`；MySQL库/表/连接排序规则为`utf8mb4_general_ci`或`utf8mb4_unicode_ci`。若已完成迁移发现乱码，需从旧库重新导出。

Q3：迁移后后台登录正常，但页面跳转还是旧域名，如何解决？
A：先删`runtime/cache`和`runtime/temp`；再全局搜索代码中硬编码的旧域名（含`config/app.php`的`app_host`、数据库里的站点配置表）；最后检查CDN或反向代理是否缓存了旧响应。

Q4：ThinkPHP5升级到6/8迁移要注意什么？
A：这是框架升级而非单纯迁移，重点：入口文件改为`public/index.php`；配置从`application/.php`迁移到`config/.php`+`.env`；`Db::name()`查询构造器、助手函数部分改名；中间件、路由写法有变化。建议先在测试环境全量回归，不要在生产直接切换版本。

Q5：迁移后出现“Class’think\facade\Db’notfound”或Composer报错？
A：Composer依赖未安装或PHP版本不匹配。执行`composerinstall–no-dev`（生产）或`composerupdate`；确认`vendor/`已上传（有些打包工具会排除）；检查新机PHP版本是否满足`composer.json`的`require`约束。

六、总结检查清单（打印版）

-[]`.env`/`config/database.php`主机、库名、账号、密码已改
-[]`app_debug`已关闭，`default_timezone`为上海
-[]Web根目录指向`public/`，伪静态规则已配
-[]`runtime`已清空，`public/uploads`权限正确
-[]硬编码旧域名/IP已全局替换
-[]Redis/缓存/Session配置已核对
-[]定时任务、队列已在新机重建
-[]表数量、记录数、上传文件数三项数据比对通过
-[]SSL证书、数据库`sql_mode`（MySQL8）已检查

按以上步骤操作，ThinkPHP站点迁移基本可以做到“零故障切换”。核心记住一句话：环境对齐+配置改全+缓存清空+数据比对。