必须确保 service.vgroupmapping.{group-name} 配置项存在、拼写准确、值非空，且与 tc 在注册中心注册的集群名完全一致；同时验证 tc 服务可达、已启动并成功注册。
检查 service.vgroupMapping 配置是否匹配 TC 服务分组
Hyperf 无法注册分支事务，或抛出 service.vgroupMapping.law-firm-group configuration item is required，本质是客户端根本没找到该事务分组对应的 TC 地址。Seata 客户端启动时会读取 service.vgroupMapping.{your-group-name} 的值（如 default://127.0.0.1:8091），再据此连接 TC；如果这个 key 不存在、拼写错误、或值为空，就会直接报错。
实操建议：
- 确认你在 Hyperf 项目中配置的事务分组名（比如
law-firm-group）和 TC 服务端实际注册到注册中心（Nacos / Eureka / file.conf）的vgroup名完全一致——大小写、下划线、连字符都不能差 - 检查配置加载路径：Hyperf 默认从
config/autoload/seata.php或环境变量注入该值，确保它最终被正确解析为service.vgroupMapping.law-firm-group形式（不是嵌套在某个数组里漏了拼接） - 若用 Nacos 管理配置，登录控制台查 Data ID 是否为
seata.properties（或你指定的 ID），Group 是否匹配，内容是否含service.vgroupMapping.law-firm-group=default - 不要复用其他语言项目的配置模板——Java 的
registry.conf和 PHP 的seata.php结构不同，硬套会导致 key 解析失败
验证 TC 服务端是否真实可连且已注册对应分组
即使配置写对了，TC 没起来、端口不通、或没注册进注册中心，Hyperf 一样连不上。Hyperf 不像 Spring Boot 有自动健康检查日志，得手动验证链路末端。
本页面提供企业级 PHP 协程框架 Hyperf 3.1.66 版本的官方源码下载与完整更新日志。重点解析 v3.1.66 版本中新增的 gRPC 多客户端负载均衡支持、Pool 连接池全量刷新、Guzzle 持久化 Cookie 以及数据库 JSON 包含键查询等核心优化特性。
实操建议：
- 在 Hyperf 服务器上执行
telnet 127.0.0.1 8091（或你配的 TC 地址+端口），确认 TCP 层通；不通就先查 TC 进程、防火墙、Docker 网络模式 - 访问 TC 控制台：
http://<tc-ip>:7091</tc-ip>，看首页是否显示 “Connected” 及在线 RM 数量；若空白或 404，说明 TC 未正常暴露 HTTP 管理端口 - 查注册中心：比如 Nacos 地址
http://localhost:8848/nacos→ 服务列表 → 搜索seata-server，确认其groupName和clusterName与你的vgroup匹配（例如vgroup=law-firm-group对应cluster=GZ，需在 TC 的application.yml中显式配置service.vgroup-mapping.law-firm-group=GZ） - TC 日志里搜
register success和global transaction manager started，没有这两句基本等于没真正启动成功
为什么 Hyperf + Seata 极易卡在这两步
Hyperf 是协程模型，Seata 的 Java TC 是线程模型，两者之间没有共享内存或进程间通信能力，全靠网络请求维系状态。一旦 vgroup 映射错或 TC 不可用，Hyperf 就会静默降级为本地事务（不报错但也不走分布式逻辑），或者在首次 BranchRegisterRequest 时因超时直接失败——而这个失败往往被框架吞掉，只留下一条模糊的“no available service”日志。
最容易被忽略的是：Hyperf 的 Seata 客户端不会主动 ping TC 健康状态，也不会缓存失败后的重试策略。它每次发起分支注册都依赖配置实时解析地址，所以哪怕 TC 中途挂掉，Hyperf 也不会感知，只会持续报连接异常，直到你人工介入。
