PHP IntlBreakIterator 的边界偏移为什么不能直接当字符序号

如果你把 IntlBreakIterator 返回的边界值直接传给 mb_substr()，中文、表情或其他多字节文本很容易出现切片错位。原因是两套 API 使用的坐标单位不同：IntlBreakIterator 的边界位置是从文本开头计算的 UTF-8 字节偏移，mb_substr() 的 start 和 length 则按字符计数。

边界值首先是“字节坐标”，不是“第几个字符”。要按原始文本片段切取，就保留它给 substr()；要按人类理解的字符位置切取，就先建立字符坐标，不能直接复用这个整数。

• 字节坐标：IntlBreakIterator 的边界和 getPartsIterator() 的左右键使用 UTF-8 字节偏移。
• 字符坐标：mb_strlen() 与 mb_substr() 按指定编码把多字节字符计为一个字符。
• 处理原则：同一段切片逻辑里不要混用两套坐标；必要时显式做字节到字符的转换。

先看清 IntlBreakIterator 返回的是什么

PHP 官方手册把 IntlBreakIterator 描述为 ICU 文本边界迭代器。遍历它时得到的是连续的边界位置，这些位置表示从文本起点开始计算的 UTF-8 code units，也就是字节数量；迭代器的键只是从 0 开始的自然数序列，不是边界在文本中的字符序号。

例如，中文字符在 UTF-8 中通常占用多个字节。边界值可能跨过了若干字节，却不等于跨过了同样数量的中文字符。因此，看到一个整数时，先问它属于哪种坐标系，比先把它传进字符串函数更重要。

最小配方：用字节边界配合 substr

如果目标是按迭代器给出的边界截取原始 UTF-8 片段，可以使用 substr()，因为它的起点和长度也按字节理解。下面的写法保留边界坐标的原意，并把相邻边界组成一个片段。

setText($text);
$boundaries = [];
foreach ($iterator as $boundary) {
    // boundary 是 UTF-8 字节偏移，不是中文字符序号。
    $boundaries[] = $boundary;
}

foreach (array_slice($boundaries, 0, -1) as $index => $left) {
    $right = $boundaries[$index + 1];
    // substr 的起点和长度都使用字节坐标，和边界值保持一致。
    $part = substr($text, $left, $right - $left);
    echo $part . PHP_EOL;
}

这段代码的关键不是“得到多少个词”，而是两端的单位一致：左边界、右边界和 substr() 都在字节坐标系里工作。真正的边界集合会受到 ICU 规则和语言环境影响，不能把示例中的每个整数解释成字符序号。

需要字符序号时，为什么要换成 mbstring

如果业务需求是“从第 3 个字符开始取 4 个字符”，应该使用 mb_substr()，并明确编码为 UTF-8。它按字符位置工作，和 IntlBreakIterator 的边界值不是同一种输入。

mb_strlen() 的作用是建立字符数量的参照，而不是把它变成边界表。若要把某个边界字节偏移换成字符位置，可以对同一段 UTF-8 前缀调用 mb_strlen(substr($text, 0, $byteOffset), 'UTF-8')；这里的 substr() 先按字节截取前缀，之后再交给 mb_strlen() 按字符计数。

getPartsIterator 的键也要按字节理解

getPartsIterator() 可以直接遍历边界之间的文本片段。手册列出了三种键类型：默认的连续序号、当前片段左侧的字节偏移，以及当前片段右侧的字节偏移。若选择左右键，键名仍然是字节坐标，不会自动变成字符序号。

setText($text);
$parts = $iterator->getPartsIterator(IntlPartsIterator::KEY_LEFT);

foreach ($parts as $leftByteOffset => $part) {
    // KEY_LEFT 是片段左边界的字节偏移，part 才是当前片段内容。
    echo $leftByteOffset . ': ' . $part . PHP_EOL;
}

这是一种更不容易混淆的写法：如果只需要片段内容，就使用迭代出来的 $part；如果还要记录原文位置，就把键命名为 $leftByteOffset，明确它是字节偏移。

following、isBoundary 和字符索引不要混用

following($offset)、preceding($offset) 和 isBoundary($offset) 接收的也是偏移量。调用它们时，应继续传入 UTF-8 字节坐标。若你的输入来自前端的字符下标、数据库里的字符位置或 mb_substr() 的计算结果，先转换坐标，再查询 ICU 边界。

setText($text);
$byteOffset = 6;

// 这里的参数必须是字节偏移，不能直接填字符下标。
$isBoundary = $iterator->isBoundary($byteOffset);
$nextBoundary = $iterator->following($byteOffset);

var_dump($isBoundary, $nextBoundary);

如果只是想在用户界面中高亮第几个字符，更适合在业务层维护字符索引，再用 mb_substr() 或按字符拆分后的数组完成展示；不要把 ICU 的偏移值伪装成 UI 层的字符序号。

常见坑点与选择清单

还要留意扩展依赖：IntlBreakIterator 属于 PHP 的 intl 扩展，mb_strlen() 和 mb_substr() 属于 mbstring 扩展。部署时应确认相应扩展已启用；否则，代码问题和运行环境问题会被混在一起。

常见问题

IntlBreakIterator 的边界值是不是字符下标？

不是。官方手册说明它表示从文本开头计算的 UTF-8 字节偏移。迭代器的键才是连续序号，而且也不是文本字符位置。

能不能把边界值直接传给 mb_substr？

不建议。mb_substr() 的位置按字符计数，直接传入字节偏移会在多字节文本上产生错位。要么使用 substr() 保持字节坐标一致，要么先转换成字符位置。

getPartsIterator 的 KEY_LEFT 是什么单位？

它表示当前片段左侧的字节偏移；KEY_RIGHT 同理表示右侧的字节偏移，默认键类型则是连续的自然数序号。

处理中文时只用 mb_strlen 就够了吗？

不一定。mb_strlen() 适合计算指定编码下的字符数，但 ICU 边界还涉及单词、句子或组合字符等规则。需要文本边界时仍应使用合适的 IntlBreakIterator 实例。