JS 日期加减怎么处理月末和闰年边界情况

一、为什么原生 Date 会在月末与闰年静默出错

ECMAScript 规范中，Date.prototype.setMonth(month[, date]) 在未显式传递第二个参数 date 时，会默认复用当前实例的 getDate() 值。该方法内部会根据设置的新月份与原日值计算时间戳毫秒数，若日数值超出了新月份的自然天数，引擎并不会抛出异常，而是将多出来的天数自动折算为正偏移量，累加到下一个月中。

这种“自动溢出（Rollover）”机制在常规日期（例如 5 月 15 日加 1 个月变成 6 月 15 日）下工作正常，但在月末与闰年场景中会引发致命缺陷：

// 案例 1：平年 1 月 31 日加 1 个月（意图得到 2 月末）
const d1 = new Date(2023, 0, 31);
d1.setMonth(d1.getMonth() + 1);
// 2023年2月只有28天，31 - 28 = 3，结果跳入3月！
console.log(d1.toISOString().slice(0, 10)); // 输出: "2023-03-03"

// 案例 2：闰年 1 月 31 日加 1 个月
const d2 = new Date(2024, 0, 31);
d2.setMonth(d2.getMonth() + 1);
// 2024年2月有29天，31 - 29 = 2，结果同样跳入3月！
console.log(d2.toISOString().slice(0, 10)); // 输出: "2024-03-02"

// 案例 3：闰年 2 月 29 日加 1 年（意图得到次年同期）
const d3 = new Date(2024, 1, 29);
d3.setFullYear(d3.getFullYear() + 1);
// 2025年非闰年没有29日，29 - 28 = 1，跳入3月！
console.log(d3.toISOString().slice(0, 10)); // 输出: "2025-03-01"

在会员订阅按月续费、账单出账周期、信用卡还款日计算等真实业务中，1 月 31 日开通按月扣费的服务如果在 3 月 3 日才扣款，不仅会导致账期计算混乱，还会产生用户资费投诉。

二、核心解法：基于“目标月上限截断”的安全计算算法

要杜绝静默溢出，关键在于打破“直接对原对象执行 setMonth”的惯性，将日期的计算拆解为结构化字段运算。算法分为五个严谨步骤：

1. 拆解源字段：提取源日期的年、月、日以及时分秒毫秒，保留原有时间精度。
2. 映射目标年月：依据偏移量推导目标年份与目标月份，正确处理跨年进位（如 11 月加 3 个月进位到次年 2 月，或 1 月减 2 个月回退到上一年 11 月）。
3. 探测目标月最大天数：利用 JavaScript 的 day 0 机制，获取目标月的真实天数。
4. 安全边界截断：取原日值与目标月最大天数的最小值，即 Math.min(originalDay, maxDays)。
5. 安全构造新实例：使用计算后的安全字段返回全新 Date 对象，确保不产生输入污染。

完整纯函数实现（零外部依赖）

以下提供生产就绪的 addMonths 与 addYears 函数，支持正负整数偏移、时间分秒保持及不可变性：

/**
 * 获取指定年月的自然天数
 * @param {number} year 完整年份，如 2024
 * @param {number} month 0-indexed 月份（0 代表 1月，1 代表 2月）
 * @returns {number} 当月实际天数（28, 29, 30 或 31）
 */
function getDaysInMonth(year, month) {
  // month + 1 指向下一个月，day 传 0 代表该下个月的第 0 天，即目标月的最后一天
  return new Date(year, month + 1, 0).getDate();
}

/**
 * 安全加减月份（采用月末上限截断策略）
 * @param {Date} date 基准日期对象
 * @param {number} monthsToAdd 增加或减少的月份数（支持负数）
 * @returns {Date} 计算后的新 Date 实例（不修改原对象）
 */
function addMonths(date, monthsToAdd) {
  const src = new Date(date.getTime());
  const originalDay = src.getDate();
  const originalMonth = src.getMonth();
  const originalYear = src.getFullYear();

  // 1. 计算总月份与目标年月
  const totalMonths = originalMonth + monthsToAdd;
  const targetYear = originalYear + Math.floor(totalMonths / 12);
  // 正确处理负数取模，保持在 0 ~ 11 范围内
  const targetMonth = ((totalMonths % 12) + 12) % 12;

  // 2. 探查目标月的最大自然天数
  const maxDaysInTargetMonth = getDaysInMonth(targetYear, targetMonth);

  // 3. 截断边界：若原日期大于目标月上限，则对齐到当月末
  const safeDay = Math.min(originalDay, maxDaysInTargetMonth);

  // 4. 构建全新 Date 实例并继承源日期的时分秒毫秒
  return new Date(
    targetYear,
    targetMonth,
    safeDay,
    src.getHours(),
    src.getMinutes(),
    src.getSeconds(),
    src.getMilliseconds()
  );
}

/**
 * 安全加减年份（处理闰年 2月29日 跨平年边界）
 * @param {Date} date 基准日期
 * @param {number} yearsToAdd 年份增减量
 * @returns {Date}
 */
function addYears(date, yearsToAdd) {
  // 年份加减等价于增减 yearsToAdd * 12 个月
  return addMonths(date, yearsToAdd * 12);
}

三、月末与闰年关键场景对照矩阵

为了验证算法的正确性，我们将原生运算与安全截断算法在各类极端边界下的实际输出进行横向对比：

四、业务策略抉择：单纯截断 vs 月末对齐（End of Month Pinning）

在实际企业系统开发中，需要厘清业务对于“月末”的定义差异。上述 addMonths 采用的是“数值截断法（Day Clamping）”，即原日值仅在超额时向下收缩。

但在某些金融或会计结算规则中，采用的是“月末对齐策略（End-of-Month Pinning）”：如果基准日期恰好是当月的最后一天（即便它是 2 月 28 日或 4 月 30 日），那么增加一个月后，结果也必须是对齐到目标月的最后一天。

/**
 * 判断某个日期是否为当月的最后一天
 */
function isEndOfMonth(date) {
  const test = new Date(date.getTime());
  test.setDate(test.getDate() + 1);
  return test.getDate() === 1;
}

/**
 * 支持“月末对齐”模式的月份增减函数
 * @param {Date} date 基准日期
 * @param {number} monthsToAdd 月份偏移
 * @param {boolean} pinToLastDay 若输入为月末，目标是否强行保持为月末
 */
function addMonthsWithPinning(date, monthsToAdd, pinToLastDay = false) {
  if (!pinToLastDay) {
    return addMonths(date, monthsToAdd);
  }

  const wasLastDay = isEndOfMonth(date);
  const result = addMonths(date, monthsToAdd);

  if (wasLastDay) {
    // 将日期强制推导至目标月的最后一天
    const maxDay = getDaysInMonth(result.getFullYear(), result.getMonth());
    result.setDate(maxDay);
  }
  return result;
}

// 业务对比示例：
const feb28 = new Date(2023, 1, 28); // 2023年2月28日（平年末）
console.log(addMonths(feb28, 1).toISOString().slice(0, 10)); 
// 普通截断法: "2023-03-28" (原为28号，3月也有28号，不触发截断)

console.log(addMonthsWithPinning(feb28, 1, true).toISOString().slice(0, 10));
// 月末对齐法: "2023-03-31" (原为2月末，加1个月后自动对齐到3月末)

五、生产环境三层方案选型与现代 Temporal 标准

针对不同规模与技术栈的工程项目，日期边界处理有三种成熟的技术路径：

• 轻量级纯原生封装：如本文实现的 addMonths，代码仅十几行，零依赖，极度适合工具函数库、微信小程序或性能敏感的服务端接口。
• 现代成熟日期库（date-fns / Day.js）：成熟库已经内置了截断处理。例如 date-fns 的 addMonths(new Date(2024, 0, 31), 1) 会输出 2024-02-29；dayjs('2024-01-31').add(1, 'month') 同样默认执行月末截断。
• 现代 ECMAScript Temporal 标准 API：作为彻底替代 Date 对象的现代国际标准（TC39 Stage 3 / 现代运行时支持），Temporal 在语言级别解决了时区与日期计算问题。

// 现代 Temporal API 规范用法（现代浏览器 / Node.js 现代版本 / Polyfill）
// Temporal.PlainDate 专注于纯日期，无时区污染
const date = Temporal.PlainDate.from('2024-01-31');

// 默认 overflow 策略即为 'constrain'（边界约束截断）
const nextMonth = date.add({ months: 1 });
console.log(nextMonth.toString()); // 输出: "2024-02-29"

// 支持显式指定严格模式：若超出天数直接抛出 RangeError 异常
try {
  const strictResult = date.add({ months: 1 }, { overflow: 'reject' });
} catch (err) {
  console.error("日期无法自然映射且不允许截断:", err.message);
}

六、易错陷阱与生产避坑清单

在编写日期边界逻辑时，除月份溢出外，以下三个高频错误也需重点防范：

• 防范原对象被就地篡改（In-Place Mutation）：原生 Date 的 setMonth、setDate 均会改变原对象状态。在编写工具函数时必须先拷贝实例，避免造成外部调用方的隐蔽副作用。
• 字符串解析时区漂移：避免使用 new Date('2024-02-29') 这种 ISO 字符串直接初始化，ISO 短格式会被部分引擎默认解析为 UTC 0 点，在东八区环境下可能发生 8 小时的日期倒退。推荐使用数字参数 new Date(year, monthIndex, day) 进行本地时间构建。
• 连续链式加减的累积失真：如果需要“连续加 1 个月并执行 3 次”，不能每次都以上一次截断后的结果作为基准。例如：1 月 31 日加 1 个月变为 2 月 29 日，如果再拿 2 月 29 日加 1 个月，就会得到 3 月 29 日（丢失了原本的 31 日特征）。正确的做法是以最初的起始锚点结合总月份增量（+1, +2, +3）统一计算。

七、单元测试验证套件

将以下测试脚本保存并在 Node.js 环境中执行，可一次性验证所有核心边界场景：

function runTestSuite() {
  const format = (d) => {
    const y = d.getFullYear();
    const m = String(d.getMonth() + 1).padStart(2, '0');
    const day = String(d.getDate()).padStart(2, '0');
    return `${y}-${m}-${day}`;
  };

  const testCases = [
    // 场景 1: 平年 1月31日 + 1月 ➔ 2月28日
    { input: new Date(2023, 0, 31), add: 1, fn: 'month', expected: '2023-02-28' },
    // 场景 2: 闰年 1月31日 + 1月 ➔ 2月29日
    { input: new Date(2024, 0, 31), add: 1, fn: 'month', expected: '2024-02-29' },
    // 场景 3: 闰年 2月29日 + 1年 ➔ 2025年2月28日
    { input: new Date(2024, 1, 29), add: 1, fn: 'year', expected: '2025-02-28' },
    // 场景 4: 闰年 2月29日 + 4年 ➔ 2028年2月29日
    { input: new Date(2024, 1, 29), add: 4, fn: 'year', expected: '2028-02-29' },
    // 场景 5: 3月31日 - 1月 ➔ 2月29日 (闰年)
    { input: new Date(2024, 2, 31), add: -1, fn: 'month', expected: '2024-02-29' },
    // 场景 6: 跨年测试: 2023年10月31日 + 4月 ➔ 2024年2月29日
    { input: new Date(2023, 9, 31), add: 4, fn: 'month', expected: '2024-02-29' }
  ];

  let passed = 0;
  testCases.forEach((tc, idx) => {
    const res = tc.fn === 'month' ? addMonths(tc.input, tc.add) : addYears(tc.input, tc.add);
    const actual = format(res);
    const isOk = actual === tc.expected;
    if (isOk) {
      passed++;
      console.log(`[PASS] 测试 ${idx + 1}: 结果 ${actual} 符合预期`);
    } else {
      console.error(`[FAIL] 测试 ${idx + 1}: 预期 ${tc.expected} 但得到 ${actual}`);
    }
  });

  console.log(`
测试汇总: 共 ${testCases.length} 项用例，通过 ${passed} 项。`);
}

runTestSuite();