ThinkPHP 6.0 升级到 8.0 并非简单改版本号：需确保 PHP≥8.0.0 且 CLI/Web SAPI 一致，启用 mbstring 等关键扩展；替换 composer.json 中 framework、think-orm、think-filesystem 版本并执行 composer why-not 排查冲突；修正模型 $name/$table 顺序及显式声明 $pkType；用 Facade 替代 input() 等废弃函数；验证第三方包兼容性，如 think-swoole 需替换、jwt-auth 需改用 lcobucci/jwt。
ThinkPHP 6.0 升级到 8.0 不是简单改个版本号就能跑通的事。核心变化集中在 PHP 环境、依赖结构、调用方式和底层行为上，稍不注意就会出现白屏、500、静默失效或逻辑跳过。下面这些点，都是真实项目里高频踩坑的位置，按模块列清楚，方便你逐项核对。
PHP 版本与扩展硬性门槛
TP8 要求 PHP ≥ 8.0.0，且 CLI 和 Web SAPI（如 Nginx + php-fpm）必须一致。常见陷阱是本地 composer update 用的是 php8.2，但服务器 fpm 还在跑 php7.4，结果依赖装上了，首页直接 500。必须同时验证：
- 执行 php -v（CLI 环境）
- 新建 info.php 写入 <?php phpinfo(); ?> 并通过浏览器访问（Web 环境）
- 检查必需扩展是否启用：mbstring、openssl、pdo_mysql、json、curl（可用 php -m | grep -E 'mbstring|openssl|pdo' 快速筛查）
composer.json 依赖替换与冲突定位
只改 "topthink/framework": "^6.1" 为 "^8.0" 是远远不够的。必须同步升级配套组件，并主动排查阻断项：
- 将 "topthink/think-orm": "^2.0" 改为 "^3.0"；"topthink/think-filesystem": "^1.0" 改为 "^2.0"
- 运行 composer why-not topthink/framework ^8.0，查看具体哪个包卡住了升级——常见拦截者是微信 SDK、支付宝 easySDK、guzzlehttp/guzzle 等老版本
- 对冲突包，优先尝试 composer update guzzlehttp/guzzle --with-dependencies；若包已废弃，需手动替换为社区维护的替代方案
模型类声明顺序与主键类型强制要求
TP8 对模型属性声明顺序做了硬性校验，错位会报 Undefined array key "table"，且堆栈不指向模型文件，极难定位：
立即学习“PHP免费学习笔记（深入）”；
- 全局搜索所有 think\Model 子类，找到 protected $name = 'xxx';
- 将其正下方的 protected $table = 'xxx'; 剪切并粘贴到 $name 行紧邻下方，中间不能有空行或注释
- 每个模型必须显式定义 $pkType：数字主键写 protected $pkType = 'int';，UUID 类写 protected $pkType = 'string';
- 所有 find() 返回值需加 is_null() 判断，旧版 === false 在 TP8 中永远不成立
助手函数全面移除与 Facade 替代规范
input()、session()、cookie()、redirect()、url()、dump()、halt() 等全部被移除，继续使用会直接触发 Fatal error: Call to undefined function：
- input('id') → \think\facade\Request::get('id')
- session('user') → \think\facade\Session::get('user')
- redirect('index/index') → return \think\facade\Redirect::to('index/index')
- dump($data) → \think\facade\Debug::dump($data)；halt($msg) → throw new \think\Exception($msg)
- 确保 config/app.php 中 'use_facade' => true，并安装 topthink/think-facade:^4.0
第三方扩展包兼容性高危清单
很多功能崩溃不是框架问题，而是第三方包没跟上 TP8 的 PSR 标准或接口变更：
- topthink/think-swoole 已废弃，必须换为 topthink/think-swoole-v8 或改用 Swoole 原生协程
- tymon/jwt-auth 仅兼容 TP6，TP8 应改用 lcobucci/jwt + 自定义中间件
- wechatpay/wechatpay-php 和 aliyun/oss-sdk-php 需在干净 TP8 环境中实测最简 API（如发消息、传空文件），不能只看 README
- phpoffice/phpspreadsheet 若低于 v1.28.0，其 ReflectionClass::getDocComment() 调用在 PHP 8.1+ 会触发弃用警告
