mb_str_pad 怎样按字符补齐多字节字符串

在 PHP 中按字符数补齐中文、日文或表情，直接使用 str_pad() 容易把字节数和字符数混在一起。PHP 8.3 起可以用 mb_str_pad()：它按 Unicode code point 计算目标长度，支持左侧、右侧和两侧补齐，返回补齐后的字符串。

官方地址：https://www.php.net/mb-str-pad

最常用的写法是 mb_str_pad($text, $target, $pad, STR_PAD_RIGHT, 'UTF-8')。先确认运行环境为 PHP 8.3 或更高版本，再根据业务需要选择补齐方向；如果目标长度不大于原字符串长度，函数会原样返回。

先把长度口径定清楚

strlen() 返回字节数，mb_strlen() 在指定编码下返回字符数；而 mb_str_pad() 的长度参数按 Unicode code point 计算。中文在 UTF-8 中通常占多个字节，但在这个函数的目标长度里只按一个字符计数。

这张图的重点不是输出样式，而是先确定“要补到多少个字符”。如果业务要求的是终端或表格的视觉列宽，还要另外考虑全角字符和表情的显示宽度，mb_str_pad() 本身不等同于屏幕宽度计算。

按方向选择右侧、左侧或两侧补齐

函数签名为 mb_str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT, ?string $encoding = null)。$length 是最终字符数，$pad_type 可以是 STR_PAD_RIGHT、STR_PAD_LEFT 或 STR_PAD_BOTH。

不要把 $length 理解为“要增加的数量”。例如原字符串有 3 个字符、目标长度是 8，实际只需要补 5 个字符。目标长度为负数、等于原长度或小于原长度时，不会发生补齐。

多字符 pad_string 只补到目标长度

$pad_string 可以是多个字符，但函数只取达到目标长度所需的部分。填充串无法整除剩余长度时，末尾可能被截断；因此不要假定每次都会完整重复一个装饰串。

如果你需要的是固定显示宽度，而不是固定 Unicode 字符数，应先定义显示宽度规则，再决定是否需要额外的宽度计算；不要仅靠重复填充字符解决视觉对齐。

没有补齐或函数不存在时怎么查

可以按下面的顺序排查，避免一上来改业务代码：

1. 函数不存在：mb_str_pad() 从 PHP 8.3 开始提供。确认 CLI、PHP-FPM 和 Web 容器实际运行的版本不是不同环境。
2. 结果没有变化：检查目标长度是否大于 mb_strlen($string, $encoding)；目标长度不够时原样返回是正常行为。
3. 中文长度不对：显式传入与输入一致的编码，例如 'UTF-8'，并确认 mbstring 扩展可用。
4. 界面看起来仍未对齐：区分字符数和显示宽度；中文全角字符、组合字符和表情可能需要单独的排版策略。
5. 两侧补齐结果和预期不同：检查是否使用了 STR_PAD_BOTH，并记住奇数个待补字符存在分配边界。

使用前的速查清单

• 环境：PHP 8.3+，并启用了 mbstring。
• 口径：目标长度按 Unicode 字符数，不是 UTF-8 字节数，也不是终端显示列宽。
• 参数：明确 pad_string、pad_type 和编码；需要稳定行为时不要省略编码。
• 边界：目标长度不大于当前长度时不补齐；多字符填充串可能被截断。
• 回归：用中文、英文、表情和空字符串各准备一个样例，分别确认右、左、两侧三种方向。

相关问题

mb_str_pad() 和 str_pad() 的主要区别是什么？

str_pad() 面向普通字符串的字节序列，而 mb_str_pad() 按多字节字符串的 Unicode 字符数处理长度。处理中文时，优先根据 PHP 版本和 mbstring 条件选择后者。

为什么目标长度写大了仍然没有补齐？

先检查传入的变量是否已经包含不可见字符，再用同一编码调用 mb_strlen()。如果当前字符数已经达到或超过目标长度，函数按设计直接返回原字符串。