PHP str_word_count 的附加字符列表怎样改变单词识别

我第一次用 str_word_count() 处理带编号的英文标签时，最容易误判的地方不是“怎么计数”，而是“哪些字符算在单词里”。这个函数的第三个参数 characters 就是调整边界的入口：它把指定的附加字符视为单词字符，但不会把函数变成通用的 Unicode 分词器。

官方地址：https://www.php.net/manual/en/function.str-word-count.php

实际使用时，可以先用 format=1 看清单词数组，再决定是否把数字、连字符或其他 ASCII 字符加入 characters。如果只需要数量，用 format=0；如果还要原文位置，用 format=2。

先看默认边界，再加入附加字符

PHP 手册把 word 定义为与 locale 有关的字母字符串，也允许单词内部出现撇号和连字符，但这两个字符不能出现在开头。数字并不自动等同于字母，所以像 v2alpha 这样的标识符，最好不要凭直觉猜结果。

这里的重点是第三个参数只描述“额外允许的字符”。字母仍按函数原本的规则识别；加入 0123456789- 后，版本号和短横线可以参与单词边界判断。不要把 characters 当作“允许字符白名单”，也不要把它写成正则表达式。

把字符列表当作输入契约的一部分

如果数据来自版本标签、文件名或简单英文标识，建议把字符列表写成有名字的变量，并在代码旁说明业务约定。这样别人看到 0123456789- 时，知道它服务于“版本号和短横线”，而不是随手放开的字符集合。

这里还要注意顺序：先确认原始数据的语义，再决定是否允许符号。若原文是自然语言而不是标识符，盲目加入短横线可能让统计口径和读者理解不一致。

根据结果用途选择 format

format 决定函数返回什么：0 返回整数计数，1 返回按出现顺序排列的单词数组，2 返回“原字符串中的位置 => 单词”的关联数组。调试字符列表时我通常先用 1；需要把结果映射回原文时再用 2。

第三种结果适合做高亮、索引或截取前几个词，但位置是原字符串中的偏移，不是数组下标。characters 改变了边界，位置映射也会随之改变，所以这两个参数应该作为同一个解析契约保存。

多字节文本和异常边界不要忽略

官方说明明确指出，str_word_count() 不支持多字节 locale。因此中文、日文或包含复杂 Unicode 组合的文本，不适合直接用它做可靠分词；应根据文本语言改用面向 Unicode 的方案。characters 也不能弥补这个限制，它只是在该函数的识别规则上增加字符。

另外，format 只能是 0、1 或 2。PHP 8 及以后传入其他值会抛出 ValueError，不要把非法值当成“返回空数组”的控制分支。

最后用一张表固定选择

这次的经验是：先用 format=1 看边界，再决定 characters，最后才选择只计数还是保留位置。这样不会因为一个数字或短横线导致统计口径悄悄变化。

常见问题

characters 可以直接写正则表达式吗？

不可以。它是附加字符列表，不是正则表达式模式；需要按字面提供要纳入识别的字符。

format=2 返回的数字是什么？

它表示单词在原字符串中的位置键，值才是对应的单词。字符列表改变边界后，这些位置也可能变化。