怎么使用dayjs或date-fns简化JS时间加减操作
深入讲解如何使用 dayjs 与 date-fns 简化 JavaScript 时间加减操作,解决原生 Date 对象原地修改副作用、跨月溢出 Bug 与复杂时间跨度计算,提供完整的代码示例与选型指南。
Date 对象进行加几天、减几月或跨时区计算非常繁琐,且原生方法(如 setDate()、setMonth())会原地修改原对象产生副作用,在遇到月末跨月(如 1 月 31 日加 1 个月意外跳到 3 月 3 日)时更极易出现隐蔽的逻辑缺陷。现代前端通常选用轻量、不可变(Immutable)的日期处理库来解决这一问题。本文将通过具体代码和实用场景,详细演示如何使用 dayjs 和 date-fns 两种业界主流方案来化繁为简,快速、可靠地完成各种时间加减操作。
一、为什么原生 JavaScript Date 的时间加减令人头疼?
在不引入任何第三方依赖的情况下,许多初学者试图通过原生方法进行时间加减。例如要计算“7 天后的时间”,通常会编写如下代码:
// 示例 1:原生 JavaScript 的原地可变修改
const today = new Date('2026-03-01T10:00:00');
const nextWeek = today; // 仅传递了引用指针
nextWeek.setDate(nextWeek.getDate() + 7);
console.log(nextWeek.toISOString()); // 输出示例: 2026-03-08T10:00:00.000Z
console.log(today.toISOString()); // 输出示例: 2026-03-08T10:00:00.000Z (today 同样被篡改!)
这种做法隐藏着两个严重陷阱:
-
可变性(Mutable)带来的状态污染: 原生
setDate()、setMonth()等方法直接原地修改原有实例。如果把这个对象当作 React/Vue 的状态变量或传递给多个组件,任何一次加减都会在不知不觉中篡改其他地方正在使用的时间引用,引发难以排查的脏数据 Bug。 -
月末溢出跳跃(Month Overflow Bug): 原生加减月份在遇到大月小月时极为脆弱。比如在 1 月 31 日调用
setMonth(getMonth() + 1),由于 2 月平年只有 28 天,原生底层会把超出边界的 3 天自动溢出到 3 月,导致结果变成了 3 月 3 日,而不是常识认知的 2 月底。
为了解决以上问题,现代社区沉淀出了两款优秀且不可变的工具库:
- dayjs: 极其轻量(压缩后仅约 2KB),拥有与老牌 Moment.js 几乎完全一致的链式 API,心智负担低。
- date-fns: 纯函数设计(Modular FP),支持极致的 Tree-shaking,用哪个函数打包哪个函数,直接操作原生 Date 对象。
二、使用 dayjs 简化时间加减操作
dayjs 采用不可变的对象模型。对任何一个 dayjs 对象调用增加或减少方法,都会返回一个全新的 dayjs 实例,原始对象始终保持纯净。
1. 安装与初始化
在项目终端中执行以下命令安装依赖:
# 在终端根目录下执行安装命令
npm install dayjs
# 或者使用 pnpm / yarn
pnpm add dayjs
在代码中引入并构造基准时间对象:
import dayjs from 'dayjs';
// 锚定基准时间:支持空参(当前时间)、ISO 8601 字符串、时间戳或原生 Date
const baseTime = dayjs('2026-03-15 14:30:00');
2. 基础加减方法:add() 与 subtract()
dayjs 将所有加法操作收敛到 .add(),所有减法操作收敛到 .subtract()。方法接收两个参数:加减的数值(整数)和时间单位字符串。
// 基础加法操作:增加天、月、年、小时
const nextDay = baseTime.add(1, 'day'); // 增加 1 天 -> 2026-03-16 14:30:00
const nextMonth = baseTime.add(1, 'month'); // 增加 1 个月 -> 2026-04-15 14:30:00
const nextYear = baseTime.add(2, 'year'); // 增加 2 年 -> 2028-03-15 14:30:00
const nextHour = baseTime.add(3, 'hour'); // 增加 3 小时 -> 2026-03-15 17:30:00
// 基础减法操作:减少天、周、分钟
const prevWeek = baseTime.subtract(1, 'week'); // 倒推 1 周 -> 2026-03-08 14:30:00
const prevMinute = baseTime.subtract(45, 'minute'); // 减少 45 分钟 -> 2026-03-15 13:45:00
// 验证不可变性:baseTime 依然是原有的 2026-03-15 14:30:00
console.log(baseTime.format('YYYY-MM-DD HH:mm:ss')); // 输出示例: 2026-03-15 14:30:00
dayjs 还支持常用的简写单位,例如 'd'(天)、'M'(月)、'y'(年)、'h'(小时)、'm'(分钟)、's'(秒)。
3. 链式调用与复杂复合时间加减
在实际业务中,经常需要复合加减多个不同维度的时间。借助 dayjs 的链式调用特性,代码可以一气呵成:
// 业务场景:计算“当前时间后移 1 个月零 3 天,再减去 2 小时 30 分钟”
const resultTime = dayjs()
.add(1, 'month')
.add(3, 'day')
.subtract(2, 'hour')
.subtract(30, 'minute');
// 格式化输出为可读文本
console.log(resultTime.format('YYYY-MM-DD HH:mm:ss'));
.startOf('day') 或 .endOf('day')。例如计算“今天起 7 天后的午夜 23:59:59”,只需写成 dayjs().add(7, 'day').endOf('day')。
三、使用 date-fns 简化时间加减操作
如果你的团队推崇函数式编程(Functional Programming),或者对项目的 Bundle 体积有极致苛刻的要求,date-fns 是绝佳选择。它不包装任何复杂对象,所有函数的入参和返回值都是纯粹的原生 JavaScript Date 对象。
1. 安装与按需引入
# 安装 date-fns 核心库
npm install date-fns
# 或者使用 pnpm / yarn
pnpm add date-fns
date-fns 的每个功能都是一个独立的纯函数。现代打包工具(Webpack、Vite、Rollup)会自动进行 Tree-shaking,未引用的函数绝不会被打包进最终产物:
import { addDays, subMonths, addHours, format } from 'date-fns';
const now = new Date('2026-03-15T14:30:00');
2. 单一语义函数加减
date-fns 提供了大量语义清晰、直观的特定单位函数,每个函数结构都是统一的 fn(date, amount):
// 针对特定单位的加减
const next3Days = addDays(now, 3); // 增加 3 天 -> 2026-03-18
const last2Month = subMonths(now, 2); // 减少 2 个月 -> 2026-01-15
const futureHour = addHours(now, 5); // 增加 5 小时 -> 19:30:00
// 验证原生不可变性:函数内部会克隆新的 Date 实例,原始 now 丝毫不受影响
console.log(now.toISOString()); // 输出示例: 2026-03-15T14:30:00.000Z
3. 使用通用的 add() 和 sub() 处理复合时间
当需要同时加减多个不同单位的时间跨度(例如:增加 1 个月、减去 2 天、增加 12 小时)时,反复嵌套函数会降低可读性。date-fns 提供了通用的 add 与 sub 函数,直接接收一个 Duration 持续时间对象:
import { add, sub, format } from 'date-fns';
const startPoint = new Date('2026-05-10T09:00:00');
// 一步完成复合时间加法
const futureDate = add(startPoint, {
years: 1,
months: 2,
days: 5,
hours: 3
});
// 一步完成复合时间减法
const pastDate = sub(startPoint, {
days: 10,
minutes: 30
});
console.log(format(futureDate, 'yyyy-MM-dd HH:mm:ss')); // 输出示例: 2027-07-15 12:00:00
console.log(format(pastDate, 'yyyy-MM-dd HH:mm:ss')); // 输出示例: 2026-04-30 08:30:00
四、关键细节:月末对齐与跨月边界机制
日期运算中最常见的“逻辑暗礁”正是月末天数不对等。例如:
- 1 月 31 日增加 1 个月,目标月份是 2 月(平年 28 天,闰年 29 天)。
- 3 月 31 日减少 1 个月,目标月份是 4 月(小月 30 天)。
原生 JS Date 的缺陷表现:
如前所述,原生 d.setMonth(d.getMonth() + 1) 在遇到 1 月 31 日时,因为 2 月没有 31 号,多出的 3 天会强行溢出进入 3 月,最终算出 3 月 3 日。
dayjs 与 date-fns 的优雅收敛表现:
两个库在月份加减中均内置了“月末对齐收敛(End-of-Month Clamping)”算法。当目标月份的总天数少于基准日的当前天数时,库会自动将日期收敛对齐至目标月份的最后一天,绝不会跨越到下下个月:
// 验证 dayjs 的月末边界收敛行为
import dayjs from 'dayjs';
const jan31 = dayjs('2026-01-31');
const endOfFeb = jan31.add(1, 'month');
console.log(endOfFeb.format('YYYY-MM-DD')); // 输出示例: 2026-02-28 (符合自然常理)
// 验证 date-fns 的月末边界收敛行为
import { addMonths, format } from 'date-fns';
const dateJan31 = new Date('2026-01-31');
const dateFeb = addMonths(dateJan31, 1);
console.log(format(dateFeb, 'yyyy-MM-dd')); // 输出示例: 2026-02-28 (同样精准收敛)
add(30, 'day') 而不是 add(1, 'month')。
五、实战业务场景代码演示
场景 1:用户权益 7 天免费试用期截止时间
在用户注册或支付成功瞬间,从当前时间起顺延 7 天,并将时间锁定在该天最后一秒(23:59:59):
// 方案 A:dayjs 实现
import dayjs from 'dayjs';
function getTrialExpireTimeDayjs() {
return dayjs()
.add(7, 'day')
.endOf('day')
.format('YYYY-MM-DD HH:mm:ss');
}
// 方案 B:date-fns 实现
import { addDays, endOfDay, format } from 'date-fns';
function getTrialExpireTimeDateFns() {
const future = addDays(new Date(), 7);
return format(endOfDay(future), 'yyyy-MM-dd HH:mm:ss');
}
场景 2:计算过去 30 天的数据统计查询区间
在后台数据大盘中,需要计算用于传递给数据库 SQL 的时间范围(起始时间为 30 天前的 00:00:00,结束时间为昨天的 23:59:59):
// 使用 dayjs 构造时间区间
import dayjs from 'dayjs';
function getStatsRange() {
const startTime = dayjs().subtract(30, 'day').startOf('day').toISOString();
const endTime = dayjs().subtract(1, 'day').endOf('day').toISOString();
return { startTime, endTime };
}
六、dayjs 与 date-fns 如何抉择?
两者都是当前前端生态中最优秀的现代时间库,选择哪一个主要取决于团队的既有规范与开发偏好:
| 对比维度 | dayjs | date-fns |
|---|---|---|
| 打包体积 | 约 2 KB(核心库完整打包) | 视引用函数而定,Tree-shaking 后数十至数百字节 |
| API 风格 | 面向对象、链式调用(Fluent API) | 纯函数、模块化(Modular Functions) |
| 数据载体 | 封装的 Dayjs 包装对象(支持 .toDate() 导出) | 直接接收并返回原生 JavaScript Date 对象 |
| Moment.js 迁移 | 无缝平替(API 几乎 100% 对应) | 需要适应纯函数写法与参数顺序 |
| 高阶扩展 | 插件机制(UTC、时区、相对时间按需 extend) | 按包拆分(如 @date-fns/tz 等) |
七、总结
原生 JavaScript 的 Date 对象因其可变副作用与跨月边界溢出,早已无法满足现代化前端与 Node.js 应用对稳定性的要求。通过引入 dayjs 或 date-fns,我们可以彻底告别繁琐的手动毫秒换算与不可预期的原地修改:
- 如果你喜欢简洁直观的链式语法,或者正在重构 Moment.js 的遗留系统,首选 dayjs,使用
.add()和.subtract()即可快速书写优雅代码。 - 如果你推崇函数式编程、使用严格的 TypeScript 开发,或者对首屏构建体积有极致要求,首选 date-fns,利用
addDays、subMonths以及通用的add/sub持续时间对象完成模块化计算。
掌握不可变的时间计算思维,不仅能够让时间加减逻辑清晰明了,更能从根本上消除生产环境中的状态污染隐患。
怎么使用D3.js绘制动态可交互的思维导图
2026-11-17 17:03:36
JS使用setInterval实现简单秒数递减倒计时
2026-11-17 16:33:13
JavaScript定义JSON时的常见语法陷阱:尾逗号与引号
2026-11-17 13:28:13
JavaScript数组sort()方法详解:语法、原理与自定义比较器
2026-11-17 13:17:39
解决JS邮箱正则匹配失败:特殊域名与中文邮箱处理
2026-11-17 12:51:31








