PHP preg_replace_callback 怎样安全处理多字节匹配结果

PHP 的 preg_replace_callback 处理中文时，需要同时守住三个约定：模式使用 /u，偏移按原文的字节理解，回调用 return 返回替换字符串。开启 PREG_OFFSET_CAPTURE 后还要调整取值方式；它不会因为启用了 UTF-8 模式就改成字符索引。本文示例面向 PHP 8，官方入口为 https://www.php.net/。

影响面：为什么英文正常，换成中文就错位

设想一个文本标记功能：找出汉字，为它加上括号，同时记录命中位置，交给后续定位功能。纯英文数据中一个 ASCII 字符通常就是一个字节，错误的坐标使用方式容易被掩盖；输入变成“中A文”，两个坐标便分开了。这是构造的排错案例，下面的结果按代码规则推导，不代表线上事故记录。

定位时可以沿着调用顺序查看：先确定传入的字符串采用什么编码，再看模式是否启用 UTF-8，然后检查回调接收的数据结构，最后看后续消费者按什么单位使用偏移。不要看到中文错位就先修改数据库字符集；正则回调与定位代码之间也可能存在单位不一致。

触发条件：一个标志改变结构，另一个修饰符改变匹配方式

/u 告诉 PCRE 把模式和目标字符串按 UTF-8 处理。例如 /\p{Han}/u 的意图是每次匹配一个汉字；这里没有 +，因此不会把相邻的一串汉字合并为一次整体匹配。它只覆盖这个字符类别，不等于所有中文标点，也不等于用户看到的所有完整字符组合。

PREG_OFFSET_CAPTURE 是另一个维度。未开启时，$matches[0] 是整体命中的文本；开启后，它变为包含文本与偏移的数组。继续把这个数组当字符串拼接，问题出在参数结构，而不是编码本身。若业务根本不需要位置，省去这个标志并直接读取文本，会更简单。

根因：UTF-8 的字符边界和字节坐标同时存在

“中A文”在 UTF-8 中占七个字节。“中”从字节 0 开始，占三个字节；“A”位于字节 3；“文”从字节 4 开始。从零计数的字符索引则分别为 0、1、2。因此第二个汉字的捕获偏移是 4，不是 2。

偏移参照传给当前匹配的目标字符串。在本文单个模式的替换中，它用于描述原文；前一次回调返回的括号已经增加了输出长度，也不会让后一个命中位置变成输出字符串的位置。后续若要在输出文本里再标注坐标，应单独维护转换关系，不能沿用原文偏移。

按字节截取和按字符截取也不能混用同一个数字。原文偏移适合与字节操作配套；需要面向用户展示字符位置时，应明确做坐标转换。即便转换为 Unicode 码点数量，也不自动等于复杂表情或组合字符的视觉数量。本例刻意限定为汉字标记，避免把两种需求混为一谈。

修复动作：完整地接住文本、偏移和失败结果

 $text, 'byte_offset' => $byteOffset];
        return '【' . $text . '】';
    },
    $subject,
    -1,
    $count,
    PREG_OFFSET_CAPTURE
);
// 失败分支立即读取错误，避免被后续正则调用覆盖。
if ($result === null) {
    throw new RuntimeException(preg_last_error_msg());
}
echo $result;
// 按规则推导：结果为【中】A【文】，替换2次，原文字节偏移为0和4。

回调只负责生成这一次命中的替换值，用 echo 打印文本不会替代返回值；它反而把输出副作用带进了处理过程。代码显式声明返回字符串，调用端再统一消费最终结果。记录数组中的字段也直接命名为 byte_offset，让消费者能够看见单位。

结果判断使用 === null。当目标参数是字符串时，正常结果仍是字符串：没有命中会保留原文；回调也可以有意返回空字符串来删除匹配。不能用 if (!$result) 把合法空结果当成执行失败。本文使用的错误消息函数属于 PHP 8，应在失败后立即读取；如果回调自身抛出异常，异常会走调用栈，不能期待只靠这个 null 分支处理所有业务错误。

防复发：把边界写入函数契约

输入端应约定 UTF-8，而不是对未知编码的数据直接追加 /u。坏编码可能让本次正则执行失败，应保留错误分支；它与合法输入恰好没有匹配是两回事。来源若有多种编码，需要按已知来源规则转换后再进入同一个文本处理函数，盲目猜测编码会把错误继续向后传递。

如果模式还有可选捕获组，不要假设每个分组一定有文本。需要稳定表达未参与匹配的分组时，可以考虑 PREG_UNMATCHED_AS_NULL，并按相应结构处理。与偏移捕获组合使用时，未匹配分组可以表现为 [null, -1]；不要拿负偏移当成真实位置，也不要把 null 解释成“整个替换失败”。这是分组层面的状态，和函数返回 null 的层级不同。

维护时保留几类能说明契约的例子即可：纯 ASCII、中英混排、相邻汉字、合法但没有命中的输入、有意删除后得到空串的输入，以及不符合编码约定的输入。关注每类的文本结果、命中数量和偏移单位，尤其避免只看最终显示是否“像对的”。对于只想替换文本的函数，去掉位置记录；对于需要坐标的函数，把原文、单位和输出坐标的转换责任一并写清楚。

参考资料

• PHP：preg_replace_callback 参数与返回值
• PHP：捕获标志与字节偏移
• PHP：PCRE 模式修饰符
• PHP：读取最近一次正则错误消息