JavaScript 原生 Date 对象怎么实现日期加减

图 0：JavaScript 原生 Date 日期加减与自动进位特性概览

一、核心机制：Date 对象的自动进位与借位

理解 JavaScript 日期加减的关键，在于掌握底层对越界数值的容错与标准化机制。当我们调用 setDate(dayValue) 时，传入的参数并不局限于当月的合法日历区间（1 到 31）。如果传入的数值超出了本月的最大天数，或者传入了小于等于 0 的负数，JavaScript 引擎并不会报错，而是会自动向上或向下换算对应的月份与年份。

例如，在一个有 31 天的月份中，如果我们执行 date.setDate(33)，引擎会自动扣除当月的 31 天，将月份加 1，并将日期设置为下个月的 2 号；同样，如果执行 date.setDate(0)，则会自动跳转到“上个月的最后一天”；执行 date.setDate(-1) 则会跳到上个月倒数第二天。

图 1：原生 setDate() 天数加减的四步执行流程与底层 Rollover 自动进位规则

二、天数加减：最标准且安全的实现方式

针对最常见的“今天加 5 天”或“指定日期前推 10 天”需求，组合使用 getDate() 与 setDate() 是业界最推荐的标准写法。这种方式完全由本地日历系统驱动，不仅语法简洁，而且能够自动识别平年（28天）、闰年（29天）以及大小月。

1. 完整实现与示例

/**
 * 安全的天数加减函数（纯函数，不修改原日期对象）
 * @param {Date|string|number} baseDate 基准日期
 * @param {number} days 增减天数（正数表示向后加，负数表示向前减）
 * @returns {Date} 返回计算后的新 Date 对象
 */
function addDays(baseDate, days) {
  // 1. 拷贝基准日期，防止修改原对象
  const result = new Date(baseDate);
  
  // 2. 获取当前月份中的日数，并累加偏移量
  // 3. 将可能超出 1~31 的新数值直接写回 setDate
  result.setDate(result.getDate() + days);
  
  return result;
}

// 验证用例 1：常规月份内加减
const start = new Date(2024, 4, 10); // 2024年5月10日
console.log(addDays(start, 5).toLocaleDateString()); 
// 输出: 2024/5/15

// 验证用例 2：自动跨月（5月有31天，10 + 25 = 35日 -> 自动进位至 6月4日）
console.log(addDays(start, 25).toLocaleDateString()); 
// 输出: 2024/6/4

// 验证用例 3：自动回退至上月（向前减 15 天）
console.log(addDays(start, -15).toLocaleDateString()); 
// 输出: 2024/4/25

// 验证用例 4：跨越平年闰年 2 月
const leapYearStart = new Date(2024, 1, 27); // 2024年是闰年，2月27日
console.log(addDays(leapYearStart, 3).toLocaleDateString()); 
// 输出: 2024/3/1（2月27 + 3天，经过28日、29日，进位到3月1日）

从上面的示例可以看到，不论是正向跨月、跨年，还是逆向回退甚至闰年 2 月的判定，浏览器与 Node.js 原生引擎内部都已经实现了精准的历法算法，开发者完全无需手动编写每个月有多少天的判断分支。

三、月份与年份加减：警惕“月末溢出”陷阱

与天数加减不同，月份的长度并非固定恒定——有的月份有 31 天，有的有 30 天，二月则有 28 或 29 天。直接套用 date.setMonth(date.getMonth() + n) 在遇到大月月末时，极易引发非预期的连跳跨月现象。

1. 陷阱重现：1月31日加1个月变成了3月

假设当前日期是 2024 年 1 月 31 日。若直接执行 date.setMonth(date.getMonth() + 1)，内部会先将月份指针挪向 2 月，同时保留原本的 31 号。但由于 2 月最多只有 29 天，合法的“2月31日”并不存在，原生引擎便会再次触发天数溢出机制，将多出的 2 天自动累加进下一个月，最终结果变成了 2024 年 3 月 2 日。原本只是希望推算“下一个月”，结果直接跳过了二月。

图 2：setMonth() 月末溢出陷阱成因剖析与基于目标月天数上限的校正方案

2. 严谨的月份加减方案（对齐月末）

在实际业务中（如信用卡账单日、按月定投日、合同到期日），用户对于“1月31日加1个月”的通常预期是落在“2月的最后一天”（即平年 2月28日，闰年 2月29日）。要达成这一目标，标准做法是在跳转月份前先将日期临时设为 1 号，跳至目标月份后再通过 Math.min(原始号数, 目标月实际最大天数) 回填。

/**
 * 健壮的月份加减函数（具备月末自动对齐保护）
 * @param {Date|string|number} baseDate 基准日期
 * @param {number} months 增减月份
 * @returns {Date} 返回对齐月末后的新 Date 对象
 */
function addMonths(baseDate, months) {
  const result = new Date(baseDate);
  const originalDay = result.getDate(); // 记录原本的日期号数，如 31

  // 1. 临时将日子重置为 1 号，避免跳转月份时因为原号数过大而直接触发跨月溢出
  result.setDate(1);
  result.setMonth(result.getMonth() + months);

  // 2. 计算当前目标月份的最大天数（利用“下个月第0天即本月最后一天”特性）
  const targetYear = result.getFullYear();
  const targetMonth = result.getMonth();
  const daysInTargetMonth = new Date(targetYear, targetMonth + 1, 0).getDate();

  // 3. 取原始号数与目标月最大天数的较小值，避免号数溢出
  result.setDate(Math.min(originalDay, daysInTargetMonth));

  return result;
}

// 验证安全加月逻辑
const jan31 = new Date(2024, 0, 31); // 2024年1月31日

// 加上 1 个月：2024年是闰年，2月最多29天，安全对齐到 2月29日
console.log(addMonths(jan31, 1).toLocaleDateString()); 
// 输出: 2024/2/29

// 加上 3 个月：4月最多30天，安全对齐到 4月30日
console.log(addMonths(jan31, 3).toLocaleDateString()); 
// 输出: 2024/4/30

3. 年份加减的对应处理

年份加减的原理与月份完全一致，通常直接使用 date.setFullYear(date.getFullYear() + n) 即可。唯一需要防范的边缘情况是闰年的 2 月 29 日加减 1 年。在平年中没有 29 号，直接 setFullYear 会跳到 3 月 1 日。若业务要求对齐到 2 月 28 日，可复用上述记录原号数并取 Math.min 的保护思路。

四、时间戳与高精度时间加减（时、分、秒与时间差）

除了修改日历字段，另一种常见的计算途径是借助 Date.prototype.getTime() 获取从 1970 年 1 月 1 日 00:00:00 UTC 开始累计的纯毫秒数。由于毫秒是一个线性的纯数字标量，在此基础上进行加减运算没有任何历法歧义。

图 3：基于本地日历语义的 Setter 机制与基于物理毫秒标量的时间戳运算对比

1. 时、分、秒的毫秒级偏移

// 常用时间单位对应的毫秒数常量
const MS_PER_SECOND = 1000;
const MS_PER_MINUTE = 60 * MS_PER_SECOND;      // 60,000
const MS_PER_HOUR   = 60 * MS_PER_MINUTE;      // 3,600,000
const MS_PER_DAY    = 24 * MS_PER_HOUR;        // 86,400,000

/**
 * 基于时间戳的高精度时间加减
 */
function addHours(baseDate, hours) {
  return new Date(new Date(baseDate).getTime() + hours * MS_PER_HOUR);
}

function addMinutes(baseDate, minutes) {
  return new Date(new Date(baseDate).getTime() + minutes * MS_PER_MINUTE);
}

// 示例：当前时间加 90 分钟
const now = new Date(2024, 9, 15, 14, 0, 0); // 14:00
const after = addMinutes(now, 90);
console.log(after.toTimeString().slice(0, 8)); // 输出: 15:30:00

2. 两个日期之间的相差天数计算

当需要反向计算“两个日期之间相隔了多少天”时，时间戳做差是最直接的方法。需要注意的是，为了避免两日期因时分秒不同导致的零碎余数，在相减前通常将两个日期的时分秒归零，或使用 Math.round / Math.floor 对最终天数做取整。

/**
 * 计算两个日期之间相差的完整自然天数
 */
function diffInDays(dateA, dateB) {
  // 仅保留年月日，剔除时分秒毫秒干扰
  const utcA = Date.UTC(dateA.getFullYear(), dateA.getMonth(), dateA.getDate());
  const utcB = Date.UTC(dateB.getFullYear(), dateB.getMonth(), dateB.getDate());

  return Math.floor((utcB - utcA) / (24 * 60 * 60 * 1000));
}

const d1 = new Date("2024-05-01");
const d2 = new Date("2024-05-18");
console.log(diffInDays(d1, d2)); // 输出: 17

五、工程实践总结与决策指南

在实际生产环境中，处理原生 JavaScript 日期运算时，只要遵循清晰的决策步骤，即可写出健壮且免于维护困扰的高质量代码。

图 4：原生 Date 日期加减运算决策路径与生产环境自查准则

日常开发中的四条核心准则

1. 始终保证纯函数操作：切忌直接对入参的 Date 实例执行 .setDate()。在操作第一行始终使用 new Date(date.getTime()) 进行深拷贝。
2. 天数加减首选 setDate：由于夏令时切换地区在特定日期可能出现一天只有 23 小时或 25 小时的情况，直接加减 86,400,000 毫秒在极少数时区下可能导致时间偏移（如变成前一天 23:00）。而 setDate(getDate() + n) 是纯粹的日历操作，不受夏令时抖动影响。
3. 月份加减必须考虑月末截断：涉及按月计算周期（如会员订阅到期）时，必须实施“临时设为 1 号并在跳转后与当月最大天数对齐”的保护逻辑。
4. 时分秒级推算使用时间戳或 setHours：对于秒、分、小时这类固定跨度的运算，直接使用毫秒偏移或 setMinutes(getMinutes() + n) 均十分稳健。