Hyperf 新手常见坑在于协程模型、生命周期和配置机制理解偏差：协程中禁用阻塞代码，避免全局变量和单例状态污染，勿硬编码配置，Nacos 需验证网络连通性与配置格式。
Hyperf 新手踩坑，大多不是能力问题，而是对协程模型、生命周期和配置机制的理解偏差。避开这些坑，关键不是背规则，而是搞清“为什么不能那样做”。
协程里别写阻塞代码
Hyperf 基于 Swoole 协程运行，一旦在协程中调用传统同步客户端（比如原生 mysqli、redis 扩展），整个协程会卡住，拖慢其他请求。这不是超时问题，是模型冲突。
- 用 hyperf/redis 和 hyperf/database 替代原生扩展，它们内部已协程化
- 禁止在协程中调用
sleep()、file_get_contents()（无协程封装）、curl_exec()（未用协程 curl） - 第三方 SDK（如支付宝、微信）若含同步 HTTP 请求，需确认是否支持协程；否则得用
Swoole\Coroutine\Http\Client重写或加协程适配层
别依赖全局变量和单例状态
Hyperf 的 Worker 进程常驻内存，Controller、Model、Service 实例默认是单例或复用的。把请求数据存到类属性或全局变量里，下一个请求会读到上一个请求的脏数据。
- 请求级数据一律通过方法参数传入，或用
Hyperf\Context\Context::set()+get()绑定当前协程上下文 - 避免在 Controller 属性里存用户 ID、token 等动态值；改用
$this->request->input()或中间件注入 - Model 查询链式调用（如
User::where(...)->with(...)）后，记得用clone或重建新实例，防止 where 条件残留
配置别硬编码，也别乱改启动方式
Hyperf Nano 是零配置，但标准 Skeleton 项目仍靠 .env 和 config/autoload/ 驱动。新手常在这两处出错：
- 改了
.env但没清 config 缓存：执行php bin/hyperf.php clear:config - 在
config/autoload/databases.php里直接写密码，应统一走$_ENV['DB_PASSWORD']，再配合dotenv加载 - Docker 启动时漏掉
-w /var/www/html工作目录参数，导致bin/hyperf.php找不到 —— 这是 Windows 上高频报错原因
服务注册与 Nacos 配置要验连通性
微服务场景下，Hyperf 接入 Nacos 最容易卡在“看似配了，实则不通”：
- 先确认 Hyperf 容器和 Nacos 容器在同一个 docker network 下（
docker network inspect xxx） - 进 Hyperf 容器，用
curl -v http://nacos:8848/nacos/v1/cs/configs?dataId=test&group=DEFAULT_GROUP测通 - Nacos 配置内容为 YAML 时，必须在 Nacos 控制台显式选择 TEXT 类型，不能选 YAML（Hyperf 默认不加载 yaml 扩展，会解析失败）
