PHP mysqli_report 怎么把查询错误变成可捕获异常

要把 MySQLi 查询错误交给 catch，在连接和查询之前显式调用 mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT)，再用 catch (mysqli_sql_exception $e) 包住可能失败的操作。只打开 ERROR 会报告警告；同时打开 STRICT，数据库操作错误才按这个组合转换成异常。

官方地址：https://www.php.net/manual/en/mysqli-driver.report-mode.php

先把“查询失败”和“没有数据”分开

下面按一个假设的排障场景展开：页面原本在查询返回 false 后展示提示，后来加了 try/catch，却仍然没有进入捕获分支。另一个常见方向恰好相反：运行环境升级后，原来的 false 判断还没执行，异常已经越过了这一段代码。这里没有真实事故时间和线上测量数据，重点是把这两种现象对应到明确的配置条件。

我会先区分错误通道，再看 SQL。本来就查不到匹配记录的 SELECT，仍然可以成功返回结果集；它与 SQL 语法错误、权限不足、连接失败属于不同情况。异常模式不能把“零行”变成错误，也不会把写入成功的 true 改成结果集。

根因通常是模式与旧代码约定不同

PHP 官方手册说明，PHP 8.1 起默认使用 ERROR 与 STRICT 的组合，之前默认为 OFF。显式配置能让应用的错误处理意图清楚可见，但仍需留意后续初始化代码是否再次修改模式。不要只凭 PHP 版本推断整个应用最终采用的模式。

这里使用位运算 | 组合标志，不是逻辑或 ||。不必为了捕获查询错误改成 ALL：ALL 还包含索引使用方面的报告，问题范围更宽。mysqli_report() 返回 true 只代表设置动作完成，不表示数据库连接或查询已经成功。

修复动作：把配置放在入口，把连接也包进 try

下面是可嵌入独立 Web 入口的示例，要求安装 MySQLi 扩展，并提前提供 DB_HOST、DB_USER、DB_PASSWORD、DB_NAME 环境变量。它使用固定只读查询，不创建业务表，不演示事务重试。示例未在本文中执行，页面文字是代码约定，并非本机运行结果。

set_charset('utf8mb4');

    // 固定只读语句，不依赖业务表；查询成功会返回结果集。
    $result = $db->query('SELECT 1 AS ready');
    $row = $result->fetch_assoc();
    echo ($row !== null && $row['ready'] == 1) ? '数据库查询可用' : '没有预期记录';
} catch (mysqli_sql_exception $e) {
    // 日志仅保留错误编号；对外不输出数据库内部消息和 SQL。
    error_log('database_operation_failed code=' . $e->getCode());
    http_response_code(503);
    echo '数据库暂时不可用';
} catch (RuntimeException $e) {
    // 本地配置错误与数据库错误分开处理。
    error_log('database_configuration_missing');
    http_response_code(500);
    echo '服务配置异常';
} finally {
    // 构造失败时 $db 仍为 null，不能直接调用 close()。
    if ($result instanceof mysqli_result) {
        $result->free();
    }
    if ($db instanceof mysqli) {
        $db->close();
    }
}

我更倾向于在应用启动处统一设置模式，数据访问函数负责抛出异常，最外层请求边界负责响应。上面的片段为了说明连接、查询和清理的范围，把它们集中在一处。若已有框架统一处理异常，应沿用框架边界，避免层层捕获后重复输出页面。

连接构造函数放在 try 内很关键：密码错误或者服务不可达时，失败可能发生在执行 SQL 之前。示例把配置缺失作为本地 RuntimeException；mysqli_sql_exception 本身继承 RuntimeException，因此专门的数据库 catch 必须放在较宽泛的 RuntimeException catch 前面。

异常对象和资源清理各管什么

$e->getCode() 可读取异常错误编号，getMessage() 用于理解具体原因；数据库内部消息适合受控诊断，不宜直接发给访问者。示例故意仅记录错误编号，实际项目可结合请求关联标识记录受控上下文，避免把密码、完整 SQL 参数或个人数据写入日志。

对外返回 503 是此示例为数据库操作失败选择的响应策略，并不意味着每个数据库异常都天然代表暂时故障。语法错误通常应修复代码，权限错误应修复授权；不能捕获到异常就一律自动重试，也不能把它改成空数组后假装业务成功。

finally 负责释放本段代码拥有的结果集和连接。new mysqli() 抛出时赋值未完成，$db 保持 null，所以先判断对象再 close。若连接由外部连接管理器提供，使用方应遵守借还约定，不照搬关闭共享连接的写法。

防止下次又出现“catch 不生效”

定位时依次阅读初始化位置、实际执行位置、捕获类型和业务返回值约定：是否在操作之前设置 ERROR | STRICT，是否被别处覆盖，出错的连接是否位于 try 内，是否使用了正确的异常类。带命名空间的文件可写 catch (\mysqli_sql_exception $e) 或先导入该类，避免解析成当前命名空间中的其他名字。

再看是否把 PHP 的错误显示设置与 MySQLi 的报告模式混为一谈。隐藏页面错误信息不能替代业务捕获；普通 catch 也不是把所有 warning 自动变为异常的开关。这里讨论的是 MySQLi 数据库操作错误，参数类型错误或其他 PHP 错误可能属于别的异常类型，不能期待这一种 catch 覆盖全部程序故障。

已经是 PHP 8.1 以后，还要手动设置吗？

默认值已是组合模式，但在统一入口显式写出配置，便于维护者理解应用约定。更重要的是避免后续代码随意切回 OFF，破坏数据访问层的异常契约。

query 返回零行，为什么没进入 catch？

零行是成功查询的一种业务结果。按结果集行数或 fetch 的返回值处理“没有记录”，不要用异常表示正常的空结果。

能否保留原来的 if ($result === false)？

在组合模式下，数据库操作失败通常会在返回值判断前抛出异常。迁移时需要调整错误分支的职责；对成功返回结果集或 true 的判断仍有意义，不能把所有返回值检查一并删掉。

最终需要统一的是一个约定：数据库操作失败进入明确的异常边界，业务无数据走正常分支，资源按所有权清理。是否执行重试、如何处理事务，需要另行设计。

参考资料：PHP MySQLi 报告模式、mysqli::query 返回值与异常、mysqli_sql_exception 类。