ThinkPHP 项目无法直接迁移至 Hyperf，因二者运行模型根本不同：前者短生命周期、同步阻塞，后者常驻内存、协程共享、非阻塞 IO；必须启用 Swoole 协程（≥5.1.0）、PHP ≥8.1、禁用短名，并将同步调用替换为协程安全版本，重构模型、数据库访问、请求上下文获取及中间件注册方式。
ThinkPHP 项目不能“平滑复制粘贴”进 Hyperf —— 直接挪控制器、模型、配置，90% 会遇到请求参数为空、数据库查不到、并发下数据错乱、服务启动后卡死或静默崩溃。根本原因不是语法不兼容，而是运行模型彻底不同：ThinkPHP 是短生命周期、进程隔离、同步阻塞；Hyperf 是常驻内存、协程共享、非阻塞 IO。
确认 Swoole 协程已启用且版本达标
这是所有迁移的前提，跳过等于白干。Hyperf 启动失败或性能无提升，八成卡在这一步。
- 执行
php --ri swoole，检查输出中必须同时满足：support coroutines => enabled且version >= 5.1.0 - 确认
php.ini中已设swoole.use_shortname = 0，否则注解扫描器会因函数名冲突静默失效 - PHP 版本必须 ≥ 8.1 —— Hyperf 3.1+ 已完全放弃对 PHP 8.0 的支持，
composer install可能跳过关键组件而不报错
替换所有同步阻塞调用为协程安全版本
ThinkPHP 里习以为常的 file_get_contents()、curl_exec()、sleep()，在 Hyperf 协程中会挂起整个 worker 进程，QPS 归零甚至引发段错误。
-
sleep(1)→ 改为co::sleep(1)（注意是co::sleep，不是Coroutine::sleep） -
file_get_contents($url)→ 改用Hyperf\HttpClient\Client实例的get()方法 -
Db::table('user')->where(...)->find()→ 必须迁移到Hyperf\Database\Connection或Hyperf\Database\Model，禁用原生 PDO 和 ThinkPHP 的 Db 类 - 第三方 SDK（如微信支付 SDK、阿里云 OSS）若未声明协程支持，必须包裹在
Hyperf\Coroutine\Waiter中，避免直接阻塞
重构模型与数据库访问方式
ThinkPHP 的 Model 是每次 new 出来的短命对象，Hyperf 的 Hyperf\Database\Model 默认常驻内存、协程共享 —— 直接复用会导致 A 用户查到 B 用户的数据、事务错乱、连接泄漏。
立即学习“PHP免费学习笔记（深入）”；
- 所有模型类不得使用
static $cache = []、protected $connection手动赋值等状态缓存逻辑 - 模型实例化必须显式声明生命周期：
@Inject(transient=true)表示每次请求新建；@Singleton仅限无状态、不持连接的极少数工具类 - 事务必须用
Hyperf\Database\Connection::transaction()，它已绑定当前协程上下文；DB::beginTransaction()+try/catch手动回滚是危险写法，漏写rollback就等于脏写 - 全局静态属性（如
Model::$with）在协程间不隔离，A 请求设置了with(['profile'])，B 请求可能意外继承 —— 应改在查询构造器链式调用中临时指定
重写入口、中间件与请求上下文获取逻辑
ThinkPHP 的 $_GET、$_POST、$this->request 在 Hyperf 中全部失效 —— 它们不是被“去掉”，而是在协程模型下无法保证线程安全，会被多个请求交叉覆盖。
- 控制器方法参数中必须声明
RequestInterface $request，再调用$request->get('id')或$request->input('name') - 中间件类需从
app/middleware移至app/Middleware，命名空间改为App\Middleware，并在config/autoload/middlewares.php中显式注册（Laravel/ThinkPHP 的自动发现机制在 Hyperf 中完全失效） - 任何工具函数或服务类中需要访问请求数据时，必须通过
Context::get(ServerRequestInterface::class)显式获取，绝不能依赖全局变量或静态属性 - 别在中间件外直接读
$_GET，哪怕只是临时调试 —— 它返回的很可能是上一个协程残留的值
最易被忽略的点是：协程上下文不是“默认存在”的，它是隐式传递的。一旦你在某个异步回调、定时任务、或手动 go() 创建的子协程里忘了传入上下文，RequestInterface、ApplicationContext、甚至数据库连接都会变成 null 或错乱实例。这不是 Bug，是协程编程的基本契约。
