number_format() 返回什么？PHP 数字格式化的常见细节和示例

PHP 的 number_format() 常用于把数字整理成便于阅读的字符串，例如将 1234567.8 显示为 1,234,567.80。它看起来像一个简单的格式化函数，但返回值类型、参数顺序、舍入规则和浮点精度都容易引发误解。

先记住最重要的一点：number_format() 返回的是字符串，不是数字。它适合生成展示文本，不适合代替数值计算，也不负责完成输入校验、货币换算或安全转义。

基本用法：返回格式化后的字符串

函数常用形式如下：

number_format(float $num, int $decimals = 0, string $decimal_separator = ".", string $thousands_separator = ","): string

它接收一个数值、要保留的小数位数、可选的小数点分隔符，以及可选的千位分隔符。返回类型为 string。

<?php
$value = 1234567.891;

$result = number_format($value);

var_dump($result);
echo $result;

默认情况下，小数位数为 0，小数分隔符是点号，千位分隔符是逗号。上例会输出：

string(9) "1,234,568"
1,234,568

因为结果是字符串，所以不要把它当作原始数字继续进行算术运算。格式化后的分隔符可能使字符串不能按预期转换为数值；即便某些情况下 PHP 能够进行转换，也不应依赖这种行为。

四个参数分别做什么

例如，使用逗号作为小数分隔符、句点作为千位分隔符：

<?php
$price = 1234567.8;

echo number_format($price, 2, ',', '.');

输出：

1.234.567,80

两个分隔符的位置很容易写反。参数顺序是小数分隔符在前，千位分隔符在后，不是按照“整数部分、再小数部分”的顺序排列。

分隔符参数是字符串，可以选择不同字符，也可以传入空字符串。例如，不想对整数进行千位分组时，可以将第四个参数设为空字符串：

<?php
echo number_format(1234567.89, 2, '.', '');

输出：

1234567.89

分隔符由调用方提供，函数不会替你根据语言、国家或用户地区自动选择。它也不会自动加上货币符号。

小数位数与舍入规则

$decimals 指定最终字符串中小数点后的位数。省略它时使用 0，传入正整数时会按指定精度舍入，并补齐不足的小数位。

<?php
echo number_format(12.3, 2) . PHP_EOL;
echo number_format(12.345, 2) . PHP_EOL;
echo number_format(12.345, 1) . PHP_EOL;
echo number_format(12.345, 0) . PHP_EOL;

输出：

12.30
12.35
12.3
12

按常见正数示例理解，保留两位时第三位小数为 5，会将第二位向上进位。函数按“半数向上”（half up）的规则舍入；对负数而言，-1.5 格式化为整数时会得到 -2。不要把它误解为“直接截掉多余小数”。

<?php
echo number_format(1.5, 0) . PHP_EOL;
echo number_format(-1.5, 0) . PHP_EOL;

输出：

2
-2

如果某个业务要求的是银行家舍入、向零截断、始终向上或始终向下，就不能直接把 number_format() 当作通用舍入策略。应先按明确的业务规则处理数值，再用合适的格式化方式输出，并针对临界值编写测试。

负数位数的版本差异

从 PHP 8.3.0 开始，$decimals 可以是负数。负数表示在小数点左侧进行舍入，例如按十位或百位舍入：

<?php
echo number_format(1234, -1) . PHP_EOL;
echo number_format(1234, -2) . PHP_EOL;

在 PHP 8.3 及以上版本中，输出分别为：

1,230
1,200

在 PHP 8.3 之前，负数位数会按 0 处理，因此上述调用不会得到按十位或百位舍入的结果。如果项目需要兼容旧版 PHP，不要依赖负数位数的行为；可以使用适当的舍入函数实现业务规则，再进行格式化。部署前也应确认运行环境版本。

千位分组不一定是逗号

默认的逗号分组适合部分英文数字展示，但不同地区的书写习惯不同。函数不会替你选择地区格式，因此应明确传入分隔符：

<?php
$value = 1234567.8;

// 逗号分组、点号小数
echo number_format($value, 2, '.', ',') . PHP_EOL;

// 点号分组、逗号小数
echo number_format($value, 2, ',', '.') . PHP_EOL;

// 空格分组、逗号小数
echo number_format($value, 2, ',', ' ') . PHP_EOL;

输出：

1,234,567.80
1.234.567,80
1 234 567,80

如果应用需要按用户所在地区格式化数字，或者需要正确处理特定货币的显示规则，可考虑 PHP 的 NumberFormatter（Intl 扩展）。它能够根据指定的区域设置提供更完整的本地化格式，而 number_format() 只按传入的分隔符执行格式化。

适用场景：用于展示，不用于计算

number_format() 适合在页面、报表或导出内容中生成可读的数字字符串，例如访问次数、统计值、价格的展示文本。实际项目中，应把用于计算的原始数据与展示用的格式化字符串分开保存。

<?php
$total = 123456.789;

// 用原始数值计算
$tax = $total * 0.1;

// 仅在输出时格式化
echo '含税金额：' . number_format($total + $tax, 2, '.', ',');

不要把格式化结果再当作金额数据写回数据库或用于计算。比如 1,234.50 是面向阅读的文本，逗号可能是分组符，也可能在某些格式中是小数符；仅凭字符串本身无法可靠判断其含义。

浮点数精度：格式化不能修复计算误差

PHP 的 float 通常采用二进制浮点表示。许多十进制小数不能被二进制浮点精确表示，因此计算结果可能带有微小误差。number_format() 只负责按指定小数位舍入显示，不会让底层浮点数变得精确。

<?php
$result = 0.1 + 0.2;

var_dump($result);
echo number_format($result, 2);

浮点结果可能显示为带有细微偏差的值，而最后一行通常显示为 0.30。这只说明输出保留了两位小数，并不证明计算过程具有十进制精确性。

涉及金额时，常见做法是以最小货币单位的整数存储和计算，例如把 12.34 元记录为 1234 分，并在展示时转换。若业务确实需要十进制精确运算，可评估 BCMath 等适合的方案。应根据币种的小数位数和业务规则处理，不要假定所有货币都固定使用两位小数。

输入值要先校验

函数的第一个参数用于接收数字，通常传入整数、浮点数或可按 PHP 规则转换的数值字符串。用户提交的内容不应未经验证就直接当作金额或计数使用。非数值输入在现代 PHP 中可能触发类型错误；具体的类型检查和转换行为还受 PHP 版本及调用方式影响。

一个基本的输入处理示例：

<?php
$input = $_POST['amount'] ?? null;

if (!is_string($input) || !is_numeric($input)) {
    throw new InvalidArgumentException('金额格式不正确');
}

$amount = (float) $input;
echo number_format($amount, 2, '.', ',');

这段代码演示的是基础的数值检查，不等同于完整的金额校验。实际应用还应定义允许的范围、负数规则、小数位数和业务精度，并避免将过大的输入直接转换为浮点数后用于关键计算。仅靠 is_numeric() 也不能替代业务规则验证。

安全边界：格式化不是转义

number_format() 不是 HTML 转义函数，也不是 SQL 防注入函数。它不会为任意字符串提供安全保证，更不能代替参数化查询。安全处理应与数字格式化分开：数据库查询使用预处理语句；输出到 HTML 时按输出上下文进行转义。

例如，将格式化结果放入 HTML 文本节点时，可以使用 htmlspecialchars()：

<?php
$formatted = number_format(1234.5, 2, '.', ',');

echo htmlspecialchars(
    $formatted,
    ENT_QUOTES | ENT_SUBSTITUTE,
    'UTF-8'
);

虽然在这些参数均为可信数字和固定分隔符时，结果通常只含数字与标点，但应用不应因此把“格式化”当作通用安全措施。尤其是分隔符来自用户输入、或结果被放入 HTML 属性、JavaScript、URL 等不同上下文时，应针对相应上下文采取正确的验证与编码。

常见错误汇总

• 以为返回的是数字：返回值是字符串。用原始数值做运算，把格式化结果留给展示。
• 参数顺序写反：第三个参数是小数分隔符，第四个参数是千位分隔符。
• 忘记默认不保留小数：省略第二个参数时默认为 0，小数会按规则舍入，而不是原样保留。
• 把舍入当成截断：函数会舍入，不是简单删除多余小数位。
• 依赖运行环境自动识别地区：该函数不会自动按语言环境选择分隔符；需要本地化时考虑 Intl。
• 将结果用于精确金额计算：浮点精度问题不会因格式化而消失，展示字符串也不适合继续计算。
• 把格式化当作安全措施：它不校验业务输入，不转义 HTML，也不防止 SQL 注入。
• 忽略 PHP 版本：负数小数位数的行为从 PHP 8.3.0 起发生变化，跨版本代码应明确处理。

一个可直接运行的综合示例

<?php
$values = [
    1234567.891,
    12.3,
    -45.678,
];

foreach ($values as $value) {
    // 默认区域风格：逗号分组，点号小数，保留两位
    $defaultStyle = number_format($value, 2);

    // 另一种常见风格：点号分组，逗号小数
    $regionalStyle = number_format($value, 2, ',', '.');

    echo '原值：' . $value . PHP_EOL;
    echo '默认风格：' . $defaultStyle . PHP_EOL;
    echo '另一种风格：' . $regionalStyle . PHP_EOL;
    echo PHP_EOL;
}

这个示例中，变量 $value 保留原始数值，$defaultStyle 和 $regionalStyle 则是用于展示的字符串。这样的分工可以减少把带分隔符的文本误用于计算或持久化的风险。

总结

number_format() 返回格式化后的字符串，适合在输出前控制小数位数和分组分隔符。使用时要确认舍入规则与 PHP 版本，牢记第三、第四参数的顺序，并区分原始数值和展示文本。对金额精度、地区化格式、输入校验和输出安全，则应分别采用相应的计算、格式化、验证与转义方案。