date-fns使用addMonths添加月份时返回结果异常问题咨询

问题根因 #

• 异常结果并非addMonths方法本身的月份计算逻辑错误，核心原因是Date.parse()解析日期字符串的时区规则不符合预期。
• ECMAScript 标准明确规定，yyyy-MM-dd格式的无时间ISO日期字符串，会被Date.parse()默认按UTC零点时间解析，而非运行环境的本地时区零点。如果运行环境时区不是UTC0，解析得到的时间戳对应的本地日期会和传入的字符串日期相差1天：
  • 例如西五区（美国东部时间）环境下，Date.parse('2023-02-15')得到的时间戳对应本地时间为2023年2月14日19点，实际传入addMonths的日期是2月14日，加1个月自然返回3月14日，和描述的异常结果完全吻合。
• 部分日期返回结果正常，是因为时差导致的日期偏移刚好没有跨自然月，加月后的日字段和预期一致。
• 给出的实现代码还存在基础语法错误：使用const声明箭头函数时缺少=和=>标识，代码无法正常被JS引擎解析，需要先修正。

date-fns addMonths 官方计算规则 #

• 基础逻辑：先给传入日期的月份字段加上指定的月数，默认保留原日期的“日”字段值。
• 边界处理逻辑：如果加完月份后，原日期的“日”值在目标月份不存在（例如1月31日加1个月到2月，平年2月没有31日），则自动回退到目标月份的最后一天。例：平年时1月31日加1个月会返回2月28日，闰年时返回2月29日。

修复方案 #

• 禁止直接使用Date.parse()解析纯日期字符串，改用date-fns自带的parse方法指定格式和时区解析，从根源避免时区偏移问题，同时修正函数语法：

import { addMonths, parse } from 'date-fns'

export const addMonth = (date, numOfMonths) => {
  // 按本地时区解析yyyy-MM-dd格式的日期字符串
  const parsedDate = parse(date, 'yyyy-MM-dd', new Date())
  return addMonths(parsedDate, numOfMonths)
}

• 如果业务需要统一使用UTC时间做日期计算，直接引入date-fns的UTC版本方法即可，无需额外做时区转换：

import { addMonths, parseISO } from 'date-fns/utc'

export const addMonth = (date, numOfMonths) => {
  const parsedDate = parseISO(date)
  return addMonths(parsedDate, numOfMonths)
}

内容的提问来源于stack exchange，提问作者sayayin