PHP preg_last_error_msg 定位 PCRE2 匹配失败

用 PHP 的 preg_last_error_msg() 定位 PCRE2 匹配失败，关键是先对 preg_match() 的返回值做严格比较，再立即保存错误码与消息。返回 0 表示本次没有匹配，返回 false 才表示发生错误；不能用一个宽松的布尔判断把两者合并。

官方地址：https://www.php.net/manual/en/

本文示例面向 PHP 8，使用固定、由开发者维护的正则。示例是供读者采用的原创写法，未在本文环境执行，不把任何输出称为实测结果。诊断目标是保留错误类别并选择处理方案，而不是让每次失败都自动提高资源限额。

先定义匹配失败的三种结果

例如用户输入不符合订单号规则，本来就可能返回 0。这不是 PCRE2 故障，不应因此告警或重试。另一个输入若编码非法，则可能使启用 UTF 模式的匹配失败，应用必须保留“执行失败”这个状态，而不是对外声称只是格式不符合。

返回值与模式编译警告的说明见 preg_match 官方文档。无效模式可以产生 E_WARNING；若项目的错误处理器将警告转换为异常，调用可能直接进入异常路径，不能假定所有配置都能继续走到返回值判断。

把错误码和消息保存在同一次调用旁

下面包装函数将本次匹配结果与错误快照绑定。它不吞掉 PHP 警告，也不执行日志格式化中的其他正则；编译警告仍由项目既有错误处理策略负责。

 $result === false
            ? 'error'
            : ($result === 1 ? 'matched' : 'not_matched'),
        'matches' => $result === 1 ? $matches : [],
        'error_code' => $errorCode,
        'error_message' => $errorMessage,
        // 只记录长度，不把原始输入写入诊断对象。
        'subject_bytes' => strlen($subject),
    ];
}

// 固定模式只接受业务允许的字符；不接收用户提交的任意模式。
$inspection = inspectMatch('~\AORD-[0-9]{6}\z~u', 'ORD-482619');
if ($inspection['status'] === 'error') {
    // 此处进入应用自己的故障路径，不能按普通未命中继续放行。
    throw new RuntimeException('订单号规则暂时无法执行');
}

preg_last_error_msg() 是 PHP 8 提供的字符串接口，无错误时返回 No error；它不接收某一次调用的句柄。错误码适合程序分支，消息适合解释原因，不建议依赖英文消息全文判断错误类别。参见 消息接口文档。

按错误类别选择修复方案

官方 错误码文档列出了 UTF-8、回溯、递归和 JIT 栈等错误。不要把每一种失败都归结为正则“太复杂”，也不要把所有资源错误映射为同一个配置项。

如果模式本身无法编译，应结合 PHP 警告中的原因检查分隔符、转义和语法，而不是只看捕获数组。诊断记录应保留规则标识，方便找到部署中的具体表达式；不必为此把含敏感内容的整个输入复制到日志。

比较输入治理与提高匹配限额

处理长文本的在线接口有请求时延和进程资源约束。建议优先比较三种方案：限制输入长度、改写含歧义的重复结构、使用专用解析器。它们分别改变可接受负载、匹配搜索空间和实现方式；选择取决于业务是否允许拒绝过长输入，以及文本是否具有需要解析的结构。

提高 pcre.backtrack_limit 可能只延后失败。pcre.recursion_limit 和 pcre.jit 又有不同含义，不能把它们当成一组越大越好的性能开关。PHP 的 运行配置文档特别提醒，高递归限额可能耗尽进程栈。修改配置应在明确的负载与资源预算下评估，不建议在通用包装函数中悄悄修改。

CLI 与 Web 请求若表现不同，记录实际 SAPI、PHP 与 PCRE 版本以及生效的配置，先解释环境差异。不能仅因开发机上的短输入成功，就认定服务中的长输入也不会失败。本文不设定通用安全长度或性能阈值。

让诊断记录适应线上请求

建议日志字段包含请求关联标识、规则标识、返回状态、错误码、消息、输入字节数和部署版本。先把这些字段保存为本地值，再交给日志组件。若日志组件内部还执行了正则，也不会改变已经保存的数组。

对外响应和内部诊断分开设计：用户可得到通用的规则暂不可用提示，维护者则能根据关联标识找到故障类型。不能为排错在响应中直接暴露完整输入、私有路径或系统配置；也不能发生引擎错误后默认把输入当成合法内容。

相同模式和输入的资源失败通常没有必要无条件立即重试。建议将失败记录与规则版本关联，修复模式或输入契约后再观察；否则重复计算只增加负载，并不能自动带来新的诊断信息。

落地清单与相关问题

• 严格区分 1、0 和 false，正常未命中不冒充故障。
• 匹配后立即读取错误码和消息，再调用可能使用正则的辅助组件。
• 保留规则标识、输入长度和环境差异，避免记录敏感原文。
• 按错误类别选择处理方案，修改限额前先明确业务与资源约束。

消息是 No error，为什么没有匹配？如果返回值为 0，这是正常未命中。无错误不等于找到了匹配。

为什么日志里的错误与调用现场不一致？应检查读取错误之前是否又执行了 preg 系列操作；最近错误不是按业务请求名称保存的历史记录。

能否通过关闭 JIT 解决所有失败？不能。编码、偏移、语法和回溯问题有各自原因。JIT 对比只能服务于具体诊断，不能当成统一修复。