Claude Code 是结构化诊断助手，需按四步精准使用：一、根据关键词定性错误层级；二、提供完整日志、版本、配置及本地验证结果；三、用诊断型/配置校验型/参数调优型三类问题提问；四、避开当搜索引擎、忽略环境差异、混淆错误层级三大陷阱。
用 Claude Code 排查 Hyperf 3.2 + Swow 的数据库配置报错，核心不是让 Claude “直接修好”，而是把它当作一个结构化诊断助手：输入准确的错误现象、环境上下文和关键日志，让它帮你定位层级、排除干扰、聚焦真实瓶颈。下面分四步说清楚怎么用才有效。
一、先确认报错属于哪一层
Hyperf 启动失败或数据库连不上，常见但混杂。Claude Code 要起作用，你得先给它“定性”。看报错文本里有没有这些关键词：
- Address already in use / failed to listen server port → 端口冲突，系统层问题，跟数据库配置无关；
- Class "Swow\Socket" not found / Socket is closed(0) → Swow 扩展没装好或没启用，PHP扩展层问题；
- Connection refused / Connection timed out / No route to host → 网络链路不通，可能是 MySQL 地址写错、防火墙拦了、Docker 网络没通；
- Access denied for user / SQLSTATE[HY000] [1045] → 用户名密码错、host 不匹配、权限没开，数据库认证层问题；
- Table doesn't exist / Unknown column → 连上了但 SQL 执行出错，是业务代码或迁移脚本问题。
二、把关键信息整理成 Claude Code 能理解的输入
别只贴一行报错。Claude Code 需要上下文才能推理。每次提问前，准备好这五项：
- 完整报错日志（含堆栈，尤其是 at 和 Caused by 行）；
- Hyperf 版本：
composer show hyperf/hyperf； - Swow 版本：
php --ri swow或swow --version； - 数据库连接配置（
config/autoload/databases.php中对应部分，隐去密码）； - 你本地验证过的事：
mysql -h 127.0.0.1 -P 3306 -u test -p能否连？telnet 127.0.0.1 3306是否通？
三、针对性问 Claude Code 的三种问法
避免泛泛而问“为什么连不上”，改用下面这三类精准提问方式：
-
诊断型：“报错显示 PDOException: SQLSTATE[HY000] [2002] Connection refused，我确认 MySQL 在 Docker 里运行，host 填的是 'mysql'，但 Hyperf 容器里
ping mysql不通 —— 是 Docker 网络配置问题，还是 Hyperf 的 DNS 解析机制有特殊要求？” -
配置校验型：“Hyperf 3.2 文档说 Swow 下要用
swow_mysql驱动，但我 config 中写的是'driver' => 'mysql'，是否必须改成'driver' => 'swow_mysql'？不改会 fallback 到什么行为？” -
参数调优型：“Swow MySQL 连接池在高并发下频繁报
Socket is closed(0)，已确认 Redis 和 MySQL 服务都正常，是否需要调整max_connections、timeout或retry_times？各参数推荐值是多少？”
四、避开三个典型误用陷阱
很多人用不好，是因为踩了这几个坑：
-
把 Claude Code 当搜索引擎用：比如问“Hyperf Swow 数据库怎么配”，它只能复述文档，没法解决你本地
.env文件路径错位的问题； -
忽略环境差异直接套答案：Claude Code 可能建议改
bind_address，但你在云数据库上根本没权限动 MySQL 配置； - 混淆错误层级后反复提问：先问“连不上 MySQL 怎么办”，再问“端口被占怎么办”，最后又问“Swow 扩展怎么装”——其实第一步 telnet 就该发现是网络不通，后面全白问。
