Hyperf 默认不支持传统文件 Session，因其常驻进程与多协程架构下文件 IO 性能差且无法跨实例共享；必须依赖 Redis 等中心化存储，需同时安装 hyperf/redis 和 hyperf/session，并正确配置 Redis 连接与 Session Handler。
Hyperf 默认不支持传统 PHP-FPM 风格的文件 Session，不是因为“不能”，而是它压根不走本地存储那条路——常驻进程 + 多协程下，文件 IO 是硬伤，且无法跨实例共享。真正在分布式环境里能用的 Session，必须靠 Redis 这类中心化存储。
确认已安装 hyperf/redis 和 hyperf/session
缺一不可。Session 组件依赖 Redis 客户端才能工作，光装 hyperf/session 会报 Class Hyperf\Redis\Redis not found。
- 执行
composer require hyperf/redis（先装 Redis 客户端） - 再执行
composer require hyperf/session（再装 Session 组件） - 运行
php bin/hyperf.php vendor:publish hyperf/redis和php bin/hyperf.php vendor:publish hyperf/session分别发布配置
检查 config/autoload/redis.php 中的连接配置
Session 要连 Redis，得先确保 Redis 连接本身是通的。重点看这几个字段是否填对：
-
host和port：别写成127.0.0.1:6379这种带端口的字符串，应分开写'host' => '127.0.0.1'、'port' => 6379 -
database：必须显式指定数字（如0），不能为null或空字符串，否则默认库可能被其他服务占用 -
password：如果 Redis 启用了 ACL（Redis 6+），这里要填user:pass格式，不是纯密码
修改 config/autoload/session.php 使用 Redis 驱动
别直接改 handler 为字符串类名，Hyperf 的 Redis Session Handler 有构造参数依赖，必须用完整配置结构：
审查 Remix v2 代码中的 v1 形态 meta 导出（v2 中为破坏性变更），cookie 安全漏洞（httpOnly、secure、密钥轮换），认证门位于错误层级，以及其他
return [
'handler' => [
'class' => \Hyperf\Session\Handler\RedisSessionHandler::class,
'constructor' => [
'redis' => make(\Hyperf\Redis\Redis::class),
'options' => [
'prefix' => 'session:',
'ttl' => 7200,
],
],
],
'options' => [
'cookie' => 'HYPERF_SESSION_ID',
'http_only' => true,
'secure' => false, // 生产环境建议设为 true（HTTPS 下）
],
];
注意：make(\Hyperf\Redis\Redis::class) 会从 DI 容器取默认 Redis 实例；若你定义了多个 Redis 连接（如 cache、session），需在 constructor 里传对应连接名，例如 'redis' => make(\Hyperf\Redis\Redis::class, ['name' => 'session'])。
验证 Session 是否真正走 Redis
最直接的办法：登录后立刻去 Redis 查 key。用 redis-cli 连上，执行：
keys session:*
应该能看到类似 session:abc123def456 的 key；再用 get session:abc123def456 看值是否是 JSON 字符串（Hyperf 默认用 json_encode 存）。如果 key 为空或返回 (nil)，说明 Session 写入失败，大概率是 Redis 连接配置错、权限不足，或 redis 实例没被正确注入进 Handler 构造函数。
一个容易被忽略的点：Hyperf 的 Session Middleware 默认只对 POST、PUT、DELETE 等非幂等请求自动启动 Session；如果是纯 GET 接口想读 Session，得手动调用 $request->getAttribute('session') 或在路由中间件中显式启用。
