PHP preg_match PREG_OFFSET_CAPTURE 的偏移量怎么用：UTF-8 字节位置与字符串截取校验

日志筛选器里，正则明明找到了“订单号”，后面的高亮位置却总是向右偏。问题通常不在 PCRE，而在于把 PREG_OFFSET_CAPTURE 返回的 UTF-8 字节偏移，当成了中文字符下标。PHP 手册明确说明，这个标志返回的是匹配内容及其在原字符串中的字节位置；要继续按字符截取，必须先转换坐标系。

先看一个会“偏右”的 UTF-8 匹配

比如你要处理混有中文描述和订单号的接口日志，需要定位订单号在原始字符串里的位置：

返回的匹配数组中，每一组结果第一个元素是匹配到的文本内容，第二个元素就是对应的偏移量。这个偏移量是从字符串起始位置开始按字节计数的，UTF-8 编码下普通汉字通常占用 3 个字节，所以这个数值不等于匹配位置之前的字符总数。要是直接把这个偏移量当成字符下标来用，后续的字符串截取很容易出现乱码、内容错位的问题。

把字节偏移转换成可用的字符位置

如果要做页面关键词高亮、内容摘要截取或者操作审计记录，需要拿到实际的字符位置，可以先取出偏移位置之前的字节片段，再统计这段片段里包含多少个 UTF-8 字符，就能得到正确的字符下标：

这里的 substr() 故意只用于切出“偏移之前”的字节片段，随后交给 mb_strlen() 做字符计数。真正按字符取上下文时，再使用 mb_substr()：

$context = mb_substr($text, max(0, $charOffset - 6), 20, 'UTF-8');

别把 strlen() 换回来。它返回的仍是字节数，中文内容一多，问题会重新出现。

匹配数组怎么取，失败时怎么判断

开启 PREG_OFFSET_CAPTURE 后，每个捕获项都会变成“文本、偏移量”的二元数组。带分组的表达式尤其容易写错下标：

[a-z0-9]+)\s+status=(?\d+)/';

if (preg_match($pattern, $text, $matches, PREG_OFFSET_CAPTURE) === 1) {
    $trace = $matches['trace'][0];
    $traceOffset = $matches['trace'][1];
    $status = $matches['status'][0];
}

preg_match() 匹配成功返回整数 1，没有匹配返回 0，正则编译失败则可能返回 false。因此不要只写 if (preg_match(...)) 来掩盖异常；在日志解析或输入校验中，用严格比较可以保留失败语义。

offset 参数不是“第几个字符”

很多代码会在循环里传入第五个参数 $offset，希望从某个中文字符开始继续匹配。PHP 手册规定，这个参数同样是字节位置，而且它和先 substr() 再匹配并不等价：正则中的 ^、$ 等断言仍然面对原始字符串。

$byteOffset = strlen('用户张三提交订单 ');
$matched = preg_match('/ORD-\d+/', $text, $matches, PREG_OFFSET_CAPTURE, $byteOffset);

如果业务输入的是“第 8 个汉字”，先用 mb_substr() 取出字符前缀，再用 strlen() 得到对应字节位置。更简单的场景可以直接对字符片段匹配，但要记住返回的偏移坐标已经相对于片段起点，需要自行加回前缀字节长度。

上线前的三组校验

• ASCII 样本：先用纯英文内容做测试，这种场景下字节偏移和字符位置数值完全一致，可以先确认你的正则规则、下标处理逻辑本身没有问题。
• 中文样本：在匹配关键词前面分别放1个、2个以及连续多段中文字符，校验转换后得到的字符位置是否符合预期。
• 边界样本：测试开头匹配、末尾匹配、未匹配、非法表达式，以及 offset 落在多字节字符中间的情况。

如果下游只需要在原字符串中做 substr() 截取，保留字节偏移反而更省事；如果要展示给用户、做字符级高亮或调用 mb_substr()，再转换成字符位置。两种坐标不要混进同一个变量名里，建议明确使用 $byteOffset 和 $charOffset。

常见问题

PREG_OFFSET_CAPTURE 返回的是字符位置吗？

不是的。它返回的匹配信息里附带的偏移量是以字节为单位的，遇到 UTF-8 编码的中文字符串，需要做额外的转换处理，得到的结果才能当作实际的字符位置来使用。

preg_match 没匹配到时 matches 会是什么？

通常返回 0，并且不能把旧的 $matches 内容当成这次结果。循环解析时应在每次调用后严格检查返回值。

为什么不能直接用 mb_substr($text, $matches[0][1], 10)？

因为 mb_substr() 的第二个参数按字符计数，而 $matches[0][1] 按字节计数。先完成字节到字符的转换，再进行字符截取。

小结

PREG_OFFSET_CAPTURE 本身没有错，真正容易出错的是把两套坐标当成一套。解析原始日志时保留字节偏移，面向用户展示时转换成字符位置，并用 ASCII、中文和边界样本各跑一遍，位置偏移问题就能在上线前暴露。