date-fns实现JS日期加减的代码示例
使用轻量 JavaScript 日期库 date-fns 实现日、月、年及时间维度的加减计算,包含完整代码示例、不可变机制分析与月末边界处理要点。
date-fns 进行日期加减,核心做法是按需引入对应的加减函数(如 addDays、subMonths 等),传入基准日期和偏移数值,直接获取返回的全新日期对象。这种纯函数方式不修改原始日期,能自然规避原生 Date 就地修改和月末溢出的常见缺陷。
一、准备工作与安装配置
date-fns 是一个轻量级、模块化的 JavaScript 日期工具库,每个功能都拆分为独立函数,原生支持 Tree-shaking。在 Node.js 或现代前端工程中,可以通过包管理工具安装:
# 使用 npm 安装
npm install date-fns
# 或使用 pnpm 安装
pnpm add date-fns
在项目中可以按需引入加减函数,支持 ES Module(import)与 CommonJS(require)两种规范。为了控制前端最终打包体积,建议直接解构导入具体函数:
// ES Module 方式引入
import { addDays, subDays, addMonths, subMonths, add, sub } from 'date-fns';
// CommonJS 方式引入
// const { addDays, subDays, addMonths, subMonths, add, sub } = require('date-fns');
二、常用单一维度的加减代码示例
实际开发中,大部分日期计算只需要针对天数、月份或年份做单一维度的平移。date-fns 提供了命名直观的加减工具函数,统一遵循 fn(date, amount) 的参数签名。
1. 天数加减:addDays 与 subDays
处理“几天后到期”或“查询过去 N 天记录”时,可以使用 addDays 和 subDays。函数接受两个参数:第一个是基准 Date 对象,第二个是要偏移的整数天数。
import { addDays, subDays } from 'date-fns';
// 设定基准日期:2025年6月1日
const baseDate = new Date(2025, 5, 1); // 月份索引从 0 开始,5 代表 6月
// 加 7 天
const nextWeek = addDays(baseDate, 7);
console.log('加7天后:', nextWeek.toISOString().slice(0, 10));
// 示例输出:加7天后: 2025-06-08
// 减 3 天
const threeDaysAgo = subDays(baseDate, 3);
console.log('减3天后:', threeDaysAgo.toISOString().slice(0, 10));
// 示例输出:减3天后: 2025-05-29
// 验证原基准日期:原对象保持不变
console.log('原基准日期未改动:', baseDate.toISOString().slice(0, 10));
// 示例输出:原基准日期未改动: 2025-06-01
2. 月份与年份加减:addMonths、subMonths、addYears
处理按月续费、年度账单时,使用 addMonths 和 addYears。与天数加减类似,直接传入年份或月份数量即可完成换算。
import { addMonths, subMonths, addYears, subYears } from 'date-fns';
const currentDate = new Date(2025, 2, 15); // 2025-03-15
// 增加 2 个月
const afterTwoMonths = addMonths(currentDate, 2);
console.log('加2个月:', afterTwoMonths.toISOString().slice(0, 10));
// 示例输出:加2个月: 2025-05-15
// 减少 1 个月
const lastMonth = subMonths(currentDate, 1);
console.log('减1个月:', lastMonth.toISOString().slice(0, 10));
// 示例输出:减1个月: 2025-02-15
// 增加 1 年
const nextYear = addYears(currentDate, 1);
console.log('加1年:', nextYear.toISOString().slice(0, 10));
// 示例输出:加1年: 2026-03-15
3. 时间维度加减:小时、分钟与秒
针对时、分、秒级别的偏移,使用对应时间粒度的函数。例如倒计时计算、会话过期时间延长等场景:
import { addHours, subMinutes } from 'date-fns';
const eventTime = new Date('2025-08-10T14:00:00Z');
// 延后 3 小时
const laterTime = addHours(eventTime, 3);
console.log('延后3小时:', laterTime.toISOString());
// 示例输出:延后3小时: 2025-08-10T17:00:00.000Z
// 提前 45 分钟
const earlyTime = subMinutes(eventTime, 45);
console.log('提前45分钟:', earlyTime.toISOString());
// 示例输出:提前45分钟: 2025-08-10T13:15:00.000Z
三、关键机制差异:原生 JS 突变与 date-fns 不可变性
在理解 date-fns 的价值时,最关键的是对比它与原生 JavaScript Date 对象的修改行为。原生 Date 的计算方法(如 setDate、setMonth)采用的是就地突变(In-place Mutation),而 date-fns 坚持不可变纯函数(Immutability)。
在相同初始条件下,观察两者的行为差异:
// 场景对比:将当前日期向后推迟 5 天
// 1. 原生 JavaScript 原地修改
const nativeDate = new Date('2025-05-01');
const aliasRef = nativeDate; // 引用同一个内存地址
nativeDate.setDate(nativeDate.getDate() + 5);
console.log(nativeDate.toISOString().slice(0, 10)); // 2025-05-06
console.log(aliasRef.toISOString().slice(0, 10)); // 2025-05-06(别名变量被连带篡改)
// 2. date-fns 纯函数计算
import { addDays } from 'date-fns';
const fnsBaseDate = new Date('2025-05-01');
const fnsNextDate = addDays(fnsBaseDate, 5);
console.log(fnsBaseDate.toISOString().slice(0, 10)); // 2025-05-01(原对象保持原样)
console.log(fnsNextDate.toISOString().slice(0, 10)); // 2025-05-06(返回独立新实例)
这一差异之所以非常重要,是因为在现代前端框架(如 React、Vue)中,状态的可预测性直接决定了组件渲染的正确性。如果一个在父组件中维护的日期对象被子组件里的原生方法修改,会导致整个数据流出现隐蔽的污染,且难以定位原因。date-fns 保证传入的原始日期始终只读,每次运算都会在内存中实例化一个全新的 Date 返回,确保数据流的安全。
四、多维度复合计算:通用 add 与 sub 函数
当业务需要同时对多个不同粒度的时间进行偏移(例如“合同签署后 1 年 3 个月零 10 天后到期”,或者“扣除 2 小时 30 分钟缓冲期”)时,连续嵌套调用多个单一函数会显得代码层级较深。此时推荐使用通用的 add 和 sub 函数。
这两个函数接收一个 Duration 配置对象作为第二个参数,可在一次调用中声明多个维度的偏移量:
import { add, sub } from 'date-fns';
const startPoint = new Date(2025, 0, 10, 9, 0, 0); // 2025-01-10 09:00:00
// 同时增加:1年、2个月、15天、3小时
const complexFuture = add(startPoint, {
years: 1,
months: 2,
days: 15,
hours: 3,
});
console.log('复合增加后:', complexFuture.toLocaleString());
// 示例输出:复合增加后: 2026/3/25 12:00:00
// 同时减少:5天、30分钟
const complexPast = sub(startPoint, {
days: 5,
minutes: 30,
});
console.log('复合减少后:', complexPast.toLocaleString());
// 示例输出:复合减少后: 2025/1/5 08:30:00
下表归纳了 Duration 对象支持的配置属性及其含义:
| 属性名称 | 数据类型 | 含义说明 |
|---|---|---|
years |
number | 偏移年份 |
months |
number | 偏移月份 |
weeks |
number | 偏移周数(1周 = 7天) |
days |
number | 偏移天数 |
hours |
number | 偏移小时数 |
minutes |
number | 偏移分钟数 |
seconds |
number | 偏移秒数 |
五、月末与闰年边界处理规则
日期加减中最容易出现线上故障的环节是月末天数不一致。例如大月有 31 天,小月有 30 天,平年 2 月只有 28 天。原生 JavaScript 在处理“1 月 31 日加一个月”时,存在自动把超额天数溢出到 3 月的机制,这往往违背了业务常理。
// 原生 JavaScript 的溢出逻辑
const nativeJan = new Date(2025, 0, 31); // 2025-01-31
nativeJan.setMonth(nativeJan.getMonth() + 1); // 试图加 1 个月
console.log(nativeJan.toISOString().slice(0, 10));
// 示例输出:2025-03-03(2月没有31天,超出的3天溢出到3月,变成3月3日)
// date-fns 的智能截断逻辑
import { addMonths } from 'date-fns';
const fnsJan = new Date(2025, 0, 31); // 2025-01-31
const fnsFeb = addMonths(fnsJan, 1);
console.log(fnsFeb.toISOString().slice(0, 10));
// 示例输出:2025-02-28(平年自动校准至2月最后一天)
// 遇到闰年时:
const leapJan = new Date(2024, 0, 31); // 2024年为闰年
const leapFeb = addMonths(leapJan, 1);
console.log(leapFeb.toISOString().slice(0, 10));
// 示例输出:2024-02-29(闰年自动校准至2月29日)
date-fns 内部通过比对目标月份的实际最大天数,在目标月份天数不足时,自动将日期对齐到目标月份的最后一天,而不会跨月跳跃。这种机制完全符合人类在处理账期、会员订阅周期的真实预期。
六、实践注意事项与常见问题排查
在生产环境中运用 date-fns 执行日期加减时,建议关注以下细节,以保证系统长期稳定运行:
-
输入参数类型校验:
date-fns的加减函数要求第一个参数为合法的Date实例或时间戳数字。如果业务数据是字符串格式(如"2025-05-01"),直接传入可能因运行环境的时区差异产生偏差。建议先使用parseISO解析成合法日期实例后再执行加减。 -
正负偏移量的语义选择:
虽然
addDays(date, -3)与subDays(date, 3)计算结果一致,但在团队协作中,优先使用明确反映业务动作的函数(向前推算用subDays,向后推算用addDays),代码的自解释性更好。 -
夏令时(DST)跨越影响:
如果系统服务跨越夏令时切换区域,
addDays保持的是“历法上的同一时刻”(即加 1 天后依然是次日的上午 10 点),而不会简单粗暴地增加绝对的 86400000 毫秒。这在涉外业务中尤为重要。 -
与格式化函数搭配使用:
加减运算输出的依旧是原生
Date对象,如果需要给前端展示或回传给后端,可以无缝搭配date-fns的format函数(例如format(resultDate, 'yyyy-MM-dd HH:mm:ss'))输出标准文本。
JS怎么保留输入数字的指定位数小数
2026-11-19 16:38:29
JavaScript常用内置函数与对象方法分类速查
2026-11-19 16:15:39
JS数组随机打乱:为什么不建议用sort实现洗牌
2026-11-19 15:36:04
JS中正整数与非负整数的正则区别是什么?
2026-11-19 14:28:20
JavaScript获取当前毫秒时间戳的常用方法
2026-11-19 14:19:28








