怎么使用dayjs或date-fns简化JS时间加减操作

作者:青柠时间:2026-11-17 19:11:48浏览:370

深入讲解如何使用 dayjs 与 date-fns 简化 JavaScript 时间加减操作,解决原生 Date 对象原地修改副作用、跨月溢出 Bug 与复杂时间跨度计算,提供完整的代码示例与选型指南。

在 JavaScript 中直接使用原生的 Date 对象进行加几天、减几月或跨时区计算非常繁琐,且原生方法(如 setDate()、setMonth())会原地修改原对象产生副作用,在遇到月末跨月(如 1 月 31 日加 1 个月意外跳到 3 月 3 日)时更极易出现隐蔽的逻辑缺陷。现代前端通常选用轻量、不可变(Immutable)的日期处理库来解决这一问题。本文将通过具体代码和实用场景,详细演示如何使用 dayjs 和 date-fns 两种业界主流方案来化繁为简,快速、可靠地完成各种时间加减操作。
怎么使用dayjs或date-fns简化JS时间加减操作
图 0:现代化 JavaScript 时间加减操作概览(链式对象与纯函数模块)

一、为什么原生 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或date-fns简化JS时间加减操作
图 1:原生 Date 可变修改陷阱与现代化不可变库计算模型对比

为了解决以上问题,现代社区沉淀出了两款优秀且不可变的工具库:

  • 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')。
怎么使用dayjs或date-fns简化JS时间加减操作
图 2:基于现代库的时间加减标准操作四步流程(导入、锚定、计算、输出)

三、使用 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 天)。
怎么使用dayjs或date-fns简化JS时间加减操作
图 3:月末跨月时间加减的溢出陷阱与自动收敛机制(Clamp to End-of-Month)

原生 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 (同样精准收敛)
注意事项: 时间单位中,“天、小时、分钟、秒”代表固定的物理时长或明确日历跨度;而“月、年”则是非定长的日历单位(28天到31天不等)。进行加减操作时,优先明确业务到底是需要“自然月跨度”(如订阅续费)还是“精确天数跨度”(如严格的 30 天试用期)。如果是后者,请明确使用 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 等)
怎么使用dayjs或date-fns简化JS时间加减操作
图 4:dayjs 与 date-fns 选型决策全景图

七、总结

原生 JavaScript 的 Date 对象因其可变副作用与跨月边界溢出,早已无法满足现代化前端与 Node.js 应用对稳定性的要求。通过引入 dayjs 或 date-fns,我们可以彻底告别繁琐的手动毫秒换算与不可预期的原地修改:

  • 如果你喜欢简洁直观的链式语法,或者正在重构 Moment.js 的遗留系统,首选 dayjs,使用 .add() 和 .subtract() 即可快速书写优雅代码。
  • 如果你推崇函数式编程、使用严格的 TypeScript 开发,或者对首屏构建体积有极致要求,首选 date-fns,利用 addDays、subMonths 以及通用的 add/sub 持续时间对象完成模块化计算。

掌握不可变的时间计算思维,不仅能够让时间加减逻辑清晰明了,更能从根本上消除生产环境中的状态污染隐患。

作者最新文章
相关文章
更多