PHP8连接Neo4j报错需按协议、端口、配置、权限四层排查：确认Neo4j启用HTTP（7474）或Bolt（7687）协议并重启；客户端匹配协议与URL编码密码；WSL2需用宿主机IP而非localhost；首次登录后必须改密且同步更新；查询须参数化绑定并用heredoc防注入。
PHP8项目连接Neo4j图数据库时出现“Connection refused”“ServiceUnavailable”或“AuthorizationFailedException”等报错，说明通信链路未打通或认证未通过，需按协议、端口、配置、权限四层逐项排查。
确认Neo4j服务状态与监听协议
先验证Neo4j是否真正运行且暴露了PHP客户端所需的接口。Neo4j 5.x默认只启用Bolt协议（端口7687），【HTTP接口（7474）默认关闭】，而graphaware/neo4j-php-client默认走HTTP，若未手动开启会直接报连接拒绝。
打开neo4j.conf文件，确认以下两行已取消注释并设为true：
dbms.connector.bolt.enabled=truedbms.connector.http.enabled=true
改完后必须重启Neo4j服务：sudo systemctl restart neo4j（Linux）或在Neo4j Desktop中Stop→Start。
立即学习“PHP免费学习笔记（深入）”；
检查PHP客户端连接方式是否匹配服务端配置
方法一：用graphaware/neo4j-php-client（推荐新手，HTTP协议，调试友好）
确保Composer已安装依赖：composer require graphaware/neo4j-php-client
连接字符串必须严格遵循http://用户:密码@主机:端口格式，例如：http://neo4j:myPass123@localhost:7474。
【密码含特殊字符（如@、/、:）必须URL编码，否则解析失败】，例如密码为p@ss/w0rd，应写成p%40ss%2Fw0rd。
方法二：用neo4j-php-driver（C扩展，Bolt协议，性能高）
需先编译安装libneo4j-client，再装PHP扩展；Windows下极不友好，【不建议Windows开发环境选用此方案】。
连接示例：$client = \Neo4j\Client::create('bolt://neo4j:myPass123@localhost:7687');
验证网络连通性与地址可达性
第一步：确认PHP所在机器能访问Neo4j服务端口。
若Neo4j运行在WSL2中，【不能用localhost直连，必须用宿主机IPv4地址】。在Windows PowerShell执行ipconfig，找到“无线局域网适配器 WLAN”下的IPv4地址（如192.168.1.105）。
第二步：在WSL2终端测试该地址端口是否通：
nc -zv 192.168.1.105 7687
看到succeeded!才表示网络层通畅；若超时或拒绝，请检查防火墙、WSL2网络模式或Docker桥接设置。
第三步：将PHP代码中的host替换为该IP，例如：http://neo4j:myPass123@192.168.1.105:7474。
处理认证失败与首次登录强制改密
Neo4j 5.x默认开启认证，初始用户名固定为neo4j，初始密码也是neo4j，但【首次登录后必须修改密码，否则后续所有连接均抛出AuthorizationFailedException】。
进入http://localhost:7474 → 输入neo4j / neo4j → 按提示设新密码（如MyNeo4j2026!）。
此后所有PHP连接字符串中的密码必须同步更新，且不能含空格或未编码的特殊字符。
执行Cypher查询前的参数化避坑步骤
① 不要拼接变量到Cypher字符串里，例如"MATCH (n) WHERE n.name = '$name'"——这会导致注入和引号冲突。
② 改用参数化绑定：$result = $client->run('MATCH (n) WHERE n.name = $name', ['name' => $name]);
③ 多行复杂查询（含APOC、URL、嵌套）必须用heredoc语法，且标识符用单引号包裹，防止PHP提前解析变量：
$query = <br><code>MATCH (u:User) RETURN u.name AS nameCYPHER;
④ 执行前先用dump($result->records());确认返回结构，避免空结果误判为连接失败。
