JS浮点数求余出现精度误差的原因及处理方法

图0：JavaScript 浮点数求余预期与真实执行表现对比

一、现象与直观表现：为什么 0.3 % 0.1 不等于 0

在纯数学逻辑中，0.3 显然是 0.1 的 3 倍整数倍，两者做求余操作的结果应当严格等于 0。但在 JavaScript 控制台中直接执行该运算，会得到一个无限逼近 0.1 的尾数，而不是 0：

// 示例 1：0.3 对 0.1 求余
console.log(0.3 % 0.1);
// 输出：0.09999999999999998

// 示例 2：10.2 对 2 求余
console.log(10.2 % 2);
// 输出：0.1999999999999993（预期应为 0.2）

// 示例 3：1.1 对 0.1 求余
console.log(1.1 % 0.1);
// 输出：2.7755575615628914e-17（极微小的非零尾数）

如果开发人员直接编写 val % step === 0 来校验输入合法性，那么当用户输入 0.3 时，校验逻辑就会立刻崩溃。要解决这个问题，首先必须认清浮点数在计算机底层的存储局限。

图1：IEEE 754 64位双精度浮点数存储与十进制小数截断机制

二、深层根因：IEEE 754 存储机制与求余运算符的误差放大

JavaScript 内部所有的数字（除 BigInt 以外）统一采用 IEEE 754 标准的 64 位双精度浮点数格式存储。这种格式将 64 个二进制位划分为三个部分：

• 符号位 (Sign, 1 bit)：决定正负号；
• 指数位 (Exponent, 11 bits)：存储偏移后的指数，偏置常数为 1023；
• 尾数位 (Mantissa / Fraction, 52 bits)：加上隐含的最高位 1，总共拥有 53 位有效精度。

1. 十进制转二进制除不尽导致的精度截断

人类使用的十进制小数以 10（2 × 5）为基底，只有分母的质因数仅包含 2 和 5 的分数才能被精确表示。而在计算机的二进制体系中，基底只有 2。十进制的 0.1 转换为二进制是乘 2 取整：

0.1 * 2 = 0.2 -> 取整 0
0.2 * 2 = 0.4 -> 取整 0
0.4 * 2 = 0.8 -> 取整 0
0.8 * 2 = 1.6 -> 取整 1
0.6 * 2 = 1.2 -> 取整 1
0.2 * 2 = 0.4 -> 取整 0 (开始循环...)
得到：0.00011001100110011...（1100 无限循环）

由于尾数位最多只能保留 53 位二进制数，超出部分必须进行舍入截断。因此在内存中：

• 0.1 实际存储的值是 0.100000000000000005551115123126（略大于 0.1）；
• 0.3 实际存储的值是 0.299999999999999988897769753748（略小于 0.3）。

2. ECMAScript 求余规范与商截断（Truncation）的连锁放大

根据 ECMAScript 语言规范，求余运算符 % 的计算公式为：

r = a - (Math.trunc(a / b) * b)

这里 Math.trunc(a / b) 代表向零取整得到整数商。当我们计算 0.3 % 0.1 时，由于分子 0.3 略微偏小、分母 0.1 略微偏大，除法操作得出的浮点商为：

0.3 / 0.1 = 2.9999999999999996

注意，2.9999999999999996 严格小于 3。当执行向零截断时，整数商被直接裁决为 2，而不是 3！接着回乘除数并相减：

r = 0.3 - (2 * 0.1) = 0.3 - 0.2 = 0.09999999999999998

本应被完整整除的除数，因为商被少算了 1，导致整整一个步长（0.1）几乎完整地滞留在了余数里。这就是浮点数求余误差最致命的放大机理。

图2：JavaScript 求余运算符（%）四步计算与误差放大推导

三、常见处理方法与代码实现

针对浮点数求余误差，业界存在三种主要处理思路：整型缩放法、容差阈值对比法以及引入高精度计算库。

图3：JavaScript 浮点求余解决方案决策流与选型矩阵

方法一：放大倍数转整型求余法（首选推荐）

核心思路：由于 JavaScript 对双精度整数（在 -2^53 + 1 到 2^53 - 1 之间）的运算是完全精确的，因此可以将小数同时乘以 10 的 N 次方转换为整数，完成求模后再除以缩放因子。

注意要点：乘法本身 a * 10^n 也会产生浮点误差（例如 0.29 * 100 === 28.999999999999996），因此必须配合 Math.round() 进行整数校准。

/**
 * 获取数值的小数位数
 */
function getDecimalPlaces(num) {
  const str = String(num);
  const dotIndex = str.indexOf('.');
  if (dotIndex === -1) return 0;
  // 兼顾科学计数法 1e-5 等特殊形式
  const eIndex = str.toLowerCase().indexOf('e');
  if (eIndex !== -1) {
    return Number(str.split('e')[1]) * -1;
  }
  return str.length - dotIndex - 1;
}

/**
 * 基于整数缩放的求余函数
 */
function scaleModulo(a, b) {
  const d1 = getDecimalPlaces(a);
  const d2 = getDecimalPlaces(b);
  const power = Math.max(d1, d2);
  const factor = 10 ** power;

  // 使用 Math.round 避免浮点乘法带来的次级误差
  const intA = Math.round(a * factor);
  const intB = Math.round(b * factor);

  return (intA % intB) / factor;
}

// 验证执行结果
console.log(scaleModulo(0.3, 0.1)); // 输出：0
console.log(scaleModulo(10.2, 2));  // 输出：0.2
console.log(scaleModulo(1.1, 0.1));  // 输出：0

方法二：结合 Number.EPSILON 阈值消除残差

在只需要判断“能否被整除”或处理 1.1 % 0.1 这种微小残差场景时，可以直接使用 ES6 引入的 Number.EPSILON（表示 1 与大于 1 的最小浮点数之差，约为 2.220446049250313e-16）。

/**
 * 浮点数整除校验
 */
function isDivisible(a, b) {
  const rem = a % b;
  // 如果余数无限接近0，或者余数无限接近除数本身（意味着商只差一点进位）
  const diffToZero = Math.abs(rem);
  const diffToDivisor = Math.abs(Math.abs(rem) - Math.abs(b));

  return diffToZero < 1e-10 || diffToDivisor < 1e-10;
}

console.log(isDivisible(0.3, 0.1)); // 输出：true
console.log(isDivisible(0.35, 0.1)); // 输出：false

方法三：借助专业十进制数学库（金融/高精度系统）

如果应用涉及外汇清算、电商计费或计税公式，绝不应该自行使用浮点运算符。推荐引入 decimal.js 或 bignumber.js，这类库使用任意精度的十进制字符串进行无损计算。

// 安装依赖：npm install decimal.js
import { Decimal } from 'decimal.js';

const result = new Decimal(0.3).mod(new Decimal(0.1));
console.log(result.toNumber()); // 严格输出：0

四、生产级安全封装与边界场景处理

在实际大型工程中，求余函数不能只考虑正常的正小数，还必须严格防范负数符号保留、除数为 0、无限值（Infinity）以及超出安全整数范围（Number.MAX_SAFE_INTEGER）等极端边界。

图4：生产级 safeRemainder 算法架构与边界防护总结

/**
 * 生产级安全求余函数
 * @param {number} a 被除数
 * @param {number} b 除数
 * @returns {number} 余数
 */
function safeRemainder(a, b) {
  // 1. 边界检查：非法数值处理
  if (Number.isNaN(a) || Number.isNaN(b) || b === 0) {
    return NaN;
  }
  if (!Number.isFinite(a) || !Number.isFinite(b)) {
    return NaN;
  }
  if (a === 0) {
    return 0;
  }

  // 2. 小数位数探测
  const getPrecision = (num) => {
    const parts = String(Math.abs(num)).split('.');
    return parts[1] ? parts[1].length : 0;
  };

  const precA = getPrecision(a);
  const precB = getPrecision(b);
  const maxDecimals = Math.max(precA, precB);

  // 3. 如果两者均为整数，直接走原生运算以保障最高性能
  if (maxDecimals === 0) {
    return a % b;
  }

  const factor = 10 ** maxDecimals;

  // 4. 超大安全整数判定保护
  if (Math.abs(a * factor) > Number.MAX_SAFE_INTEGER || 
      Math.abs(b * factor) > Number.MAX_SAFE_INTEGER) {
    // 超出 53 位安全整型时，转用 BigInt 计算
    const bigA = BigInt(Math.round(a * factor));
    const bigB = BigInt(Math.round(b * factor));
    return Number(bigA % bigB) / factor;
  }

  // 5. 常规整型安全缩放求模
  const intA = Math.round(a * factor);
  const intB = Math.round(b * factor);
  const rawRemainder = (intA % intB) / factor;

  // 6. 消除最后一步反除可能带来的极微小数尾噪
  return Number(rawRemainder.toFixed(maxDecimals));
}

五、测试验证与方案对比

为了验证 safeRemainder 的可靠性，我们将各种易出故障的边界浮点用例输入该函数与原生 % 进行了对照测试：

六、工程实践总结与开发建议

在实际项目编码中，面对浮点数求余，建议团队统一遵守以下三条工程准则：

1. 禁止直接使用 % === 0 判断浮点步长：在 UI 组件（如 Slider、InputNumber）的步长验证中，切勿直接用原生求余判断是否整除。应改用 safeRemainder(val, step) === 0 或使用带容差的浮点比较函数。
2. 轻量级场景采用整数缩放，杜绝复杂外部引入：对于常规数据可视化、图形变换与进度计算，封装几十行的 safeRemainder 即可彻底解决问题，无需为此引入数百 KB 的重量级高精度库。
3. 金融与核心账目强制使用十进制数据结构：对于涉钱场景，从数据存储到前端展现，统一使用字符串传递并在客户端使用 decimal.js 实例进行运算，从源头上切断 IEEE 754 二进制舍入带来的资损风险。