JS日期库选型:Day.js、date-fns与Moment.js对比

作者:听澜

时间:2026-11-16

浏览:85

深度对比JavaScript主流日期库Day.js、date-fns与Moment.js:涵盖打包体积、不可变性、Tree-shaking、API设计范式、时区国际化处理及平滑迁移方案,助你做出科学的技术选型。

文章目录

一、核心技术指标横向对照(结论先行)

在深入技术细节之前,可以通过以下关键指标矩阵快速建立三个库的横向认知。判断的核心在于区分项目属于“老项目平滑重构”、“轻量 Web/H5 敏捷开发”还是“重度 TypeScript 企业级系统”:

对比维度 Moment.js Day.js date-fns
当前维护状态 官方维护模式(仅修复重大安全漏洞,不再演进) 积极维护(社区活跃,插件生态完备) 积极维护(长期迭代,TS 体系标准)
打包体积 (Gzip) 约 70KB ~ 280KB(默认全量捆绑多语言与运算) 核心包仅约 2KB(插件按需另计) 单函数 300B ~ 几KB(用多少打包多少)
Tree-shaking 支持 不支持(单体对象无法静态剔除无用代码) 核心不可摇树,依赖插件按需注册 100% 完美支持(纯 ES Module 导出)
实例不可变性 可变(Mutable,原地操作,易引发并发副作用) 严格不可变(Immutable) 严格不可变(纯函数接收原生 Date)
API 设计范式 面向对象链式调用(moment().add().format()) 面向对象链式调用(高仿 Moment 语法习惯) 函数式编程(format(addDays(date, 1)))
TypeScript 适配 依赖第三方 @types/moment 内置类型定义(插件需扩展声明) 原生纯 TypeScript 编写,类型推导极精准
Moment 迁移难度 基准源 极低(95% API 完全对齐,改 import 即可) 中等(需改写为传参调用风格)
JS日期库选型:Day.js、date-fns与Moment.js对比
图 1:Moment.js 单体大包、Day.js 极简微核心与 date-fns 模块化纯函数架构形态对比

二、关键选型考量与技术差异深剖

1. 打包体积与构建优化(Tree-shaking 机理分析)

在现代前端工程中,包体积直接制约首屏加载性能与移动端用户体验。Moment.js 之所以被现代构建流淘汰,核心原因在于其历史悠久的单体架构(Monolithic Architecture)。在 Webpack 或 Vite 打包时,哪怕只使用了一个 moment().format('YYYY-MM-DD'),打包器也会将包含历法计算、相对时间推导以及全量多语言包(数百个 Locale 文件)整体打包进产物,体积常突破 70KB Gzip(未剥离多语言时甚至超过 200KB)。即便通过配置 ContextReplacementPlugin 强制剔除多语言,核心底座依然沉重。

Day.js 的解法是“微核心 + 插件系统”:其核心体积仅约 2KB,只保留了最常用的日期创建、获取、设置和基础格式化能力。像复杂相对时间(relativeTime)、UTC 解析(utc)、时区转换(timezone)或高级历法换算均封装为独立插件文件。开发者只有显式调用 dayjs.extend(plugin) 时,对应代码才会被打包器打包,有效将应用基础体积压制在极低水平。

date-fns 的解法则是“纯模块化 Tree-shaking”:date-fns 内部没有类,没有包装对象,每个功能点都是一个完全独立的纯函数文件(如 addDays.js、format.js)。基于现代 ES Module 的静态分析能力,打包工具能够精准识别并仅打包你在代码中 import 的函数本身,未引用的数百个工具函数会被打包器自动剔除,实现真正的“零废代码打包”。

2. 不可变性(Immutability)与可变对象的“副作用陷阱”

除了包体积,运行时可靠性是区分现代日期库与传统日期库的最核心技术分水岭。Moment.js 采用的是历史上的原地可变(In-place Mutation)模式。调用 add()、subtract() 等操作方法时,它并不是返回一个新的时间对象,而是直接修改了调用者自身的内存状态。

可变性踩坑典型场景: 当一个日期对象作为 props 传入子组件,或者在函数内部调用了 date.add(7, 'days') 试图计算下周时间时,外层原始的 date 变量已经被悄悄修改成了下周的时间。在 React、Vue 等倡导单向数据流与响应式触发的框架中,这种隐式修改会导致数据流错乱、缓存命中失败或无法预测的重复渲染。为了安全,Moment.js 必须强制写成 date.clone().add(...),这不仅增加了样板代码,还极易被开发者遗漏。
JS日期库选型:Day.js、date-fns与Moment.js对比
图 2:可变性(Mutable)对象共享修改陷阱与不可变性(Immutable)安全流转机制

如图 2 所示,Day.js 与 date-fns 均在设计层面保证了严格的不可变性(Immutable):

  • Day.js:所有的修改方法均会返回一个深拷贝后的全新 Dayjs 包装对象,原对象在内存中始终保持只读,完全消除意外篡改风险。
  • date-fns:基于函数式编程设计,函数入参接收原生 Date 对象,处理后返回一个全新的原生 Date 实例,原有入参绝不发生任何属性变更。

3. API 设计哲学:链式调用 vs 函数式组合

API 设计范式的偏好直接决定了团队日常编码的舒适度:

面向对象链式语法(Day.js):将时间概念封装为对象,通过点号操作符连续调用:

// Day.js 链式调用示例
const displayStr = dayjs('2026-05-15')
  .add(3, 'day')
  .startOf('month')
  .format('YYYY-MM-DD');

这种语法直观顺畅,符合自然阅读逻辑,在编写业务 UI 展示逻辑时非常顺手,且对于有 Moment.js 经验的开发者而言几乎零学习成本。

函数式编程组合(date-fns):不包装实例,直接操作原生类型,便于与 Ramda、Lodash 或原生 Array.map 协同配合:

// date-fns 函数式调用示例
import { addDays, startOfMonth, format } from 'date-fns';

const rawDate = new Date('2026-05-15');
const displayStr = format(
  startOfMonth(addDays(rawDate, 3)),
  'yyyy-MM-dd'
);

函数式风格的代码极度便于单独针对每个工具函数进行单元测试和 Mock,纯函数无状态无包装,不会出现包装类与原生 Date 频繁互转的开销。

4. TypeScript 原生工程化契合度

Moment.js 诞生于早期的 CommonJS 时代,其类型定义文件是在 TypeScript 兴起后通过社区补充维护的,类型提示层级深且存在不少 any 逃逸。

Day.js 提供了官方的 .d.ts 类型文件,对于核心方法能提供完整的类型推导;但在使用扩展插件时,开发者需要在 tsconfig.json 或全局类型文件中使用 declare module 'dayjs' 对插件类型进行声明融合,否则可能会出现 TypeScript 报 Property does not exist on type 'Dayjs' 的类型报错。

date-fns 目前完全由 TypeScript 原生编写,每个函数的输入参数、可选配置项、返回值类型均经过极严格的泛型约束,代码补全准确率与类型安全性在三者中表现最为出色,极为契合大型严谨的企业级 TS 工程。

三、选型决策流程与落地路径

在明确了体积、不可变性与 API 风格后,读者可以通过以下标准化决策流程,针对具体的项目类型与团队架构做出明确的技术选型:

JS日期库选型:Day.js、date-fns与Moment.js对比
图 3:基于业务类型、架构约束与代码风格的标准化选型推导图

场景一:既有存量项目从 Moment.js 迁出

直接选用 Day.js。由于 Day.js 的 API 绝大多数与 Moment.js 1:1 对齐,重构过程几乎只需要在打包配置中将 moment 路径别名(alias)指向 dayjs,并补齐对应的插件引用。团队无需大范围重写业务代码与单元测试,几天内就能将打包体积骤降几十千字节,投资回报率极高。

场景二:移动端 H5、营销活动页及轻量 Web 前端

优先选用 Day.js。移动端和 C 端前台对初始 Bundle 体积、页面首屏加载时间(FCP/LCP)极为苛刻。Day.js 约 2KB 的核心体积极小,链式调用适合快速书写交互逻辑,能够以最小的开销满足常规日期展示与计算需求。

场景三:大型中后台管理系统、Node.js 服务端与严谨 TS 项目

优先选用 date-fns。在中大型企业级项目或 Node.js 服务端,打包构建系统对代码树摇(Tree-shaking)支持完备,纯函数能很好地规避共享状态带来的深层 Bug。此外,结合 TypeScript 强大的类型推断与函数式流水线管道(Pipeline),date-fns 在长周期迭代中的可维护性和代码健壮性远高于其他方案。

场景四:仅需基础格式化展示的新型现代浏览器环境

优先选用原生 Web API(Intl.DateTimeFormat)。如果业务需求仅为把时间戳展示为本地格式(例如“2026年11月12日”或“上午10:30”),完全不需要引入任何第三方库。现代浏览器原生支持的 Intl 命名空间开箱即用,0KB 网络负载,性能最优。

四、典型场景代码对照与实战示例

以下通过五个日常开发中最核心的高频场景,对比 Day.js 与 date-fns 的实际编码写法与注意事项。

1. 日期格式化(注意 Token 规则差异)

重要避坑提醒: Moment.js 与 Day.js 遵循的是相同的传统 Token:年份为大写 YYYY,月份为 MM,日期为 DD。
而 date-fns 遵循 Unicode 国际标准 Token:四位年份必须使用小写 yyyy,大写 YYYY 代表“周数计年(Week-numbering year)”,跨年当周可能导致年份提前递增;天数必须使用小写 dd。
// 场景 1:格式化当前时间为 "2026-05-20 14:30:00"

// --- Day.js 写法 ---
import dayjs from 'dayjs';
const resDayjs = dayjs().format('YYYY-MM-DD HH:mm:ss');
// 示例输出: "2026-05-20 14:30:00"

// --- date-fns 写法 ---
import { format } from 'date-fns';
const resDateFns = format(new Date(), 'yyyy-MM-dd HH:mm:ss');
// 示例输出: "2026-05-20 14:30:00"

2. 日期增减运算与时间界限获取

// 场景 2:计算指定日期 3 天后的当月开始时间 (00:00:00)
const baseDate = new Date('2026-05-20T10:00:00Z');

// --- Day.js 写法 ---
const startOfMonthDayjs = dayjs(baseDate)
  .add(3, 'day')
  .startOf('month')
  .toDate();

// --- date-fns 写法 ---
import { addDays, startOfMonth } from 'date-fns';
const startOfMonthDateFns = startOfMonth(addDays(baseDate, 3));

3. 日期差值计算(Diff)

// 场景 3:计算两个日期相差的天数
const dateA = new Date('2026-06-01');
const dateB = new Date('2026-06-15');

// --- Day.js 写法 ---
const diffDaysDayjs = dayjs(dateB).diff(dateA, 'day');
// 示例输出: 14

// --- date-fns 写法 ---
import { differenceInDays } from 'date-fns';
const diffDaysDateFns = differenceInDays(dateB, dateA);
// 示例输出: 14

4. 相对时间计算(Relative Time)

计算例如“3天前”、“刚刚”等展示文案。Day.js 需引入插件并加载中文语言包;date-fns 直接导入函数并传入 locale 配置。

// --- Day.js 写法 ---
import dayjs from 'dayjs';
import relativeTime from 'dayjs/plugin/relativeTime';
import 'dayjs/locale/zh-cn';

dayjs.extend(relativeTime);
dayjs.locale('zh-cn');

const fromNowDayjs = dayjs('2026-05-18').fromNow();
// 示例输出: "2天前"

// --- date-fns 写法 ---
import { formatDistanceToNow } from 'date-fns';
import { zhCN } from 'date-fns/locale';

const fromNowDateFns = formatDistanceToNow(new Date('2026-05-18'), {
  addSuffix: true,
  locale: zhCN
});
// 示例输出: "2天前"

5. 时区处理(Timezone)

处理国际化业务时经常需要指定时区显示(如将 UTC 时间转换为 Asia/Shanghai 或 America/New_York 时间):

// --- Day.js 时区处理 ---
import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';

dayjs.extend(utc);
dayjs.extend(timezone);

const nyTime = dayjs('2026-05-20T12:00:00Z')
  .tz('America/New_York')
  .format('YYYY-MM-DD HH:mm:ss');

// --- date-fns 时区处理 (借助现代 @date-fns/tz) ---
import { formatInTimeZone } from 'date-fns-tz';

const nyTimeFns = formatInTimeZone(
  '2026-05-20T12:00:00Z',
  'America/New_York',
  'yyyy-MM-dd HH:mm:ss'
);

五、从 Moment.js 平滑迁移的实施建议与避坑指南

如果要将现有存量项目从 Moment.js 迁出,按以下规范步骤实施能够最大程度防范回归故障:

  1. 优先选择 Day.js 逐步平替:在 package.json 中安装 dayjs。如果是大型 Webpack/Vite 项目,可以在构建配置中配置别名:
    resolve: {
      alias: {
        moment: 'dayjs'
      }
    }
  2. 补齐必要插件初始化:Moment.js 默认内置的能力在 Day.js 中需要显式引入。建议在项目入口文件(如 main.ts 或 index.js)中统一完成插件扩展:
    import dayjs from 'dayjs';
    import customParseFormat from 'dayjs/plugin/customParseFormat';
    import isSameOrAfter from 'dayjs/plugin/isSameOrAfter';
    import isSameOrBefore from 'dayjs/plugin/isSameOrBefore';
    
    dayjs.extend(customParseFormat);
    dayjs.extend(isSameOrAfter);
    dayjs.extend(isSameOrBefore);
  3. 自查 clone() 代码调用:旧代码中因为防范 Moment 可变性而编写的大量 .clone() 可以保留(Day.js 提供了同名空转或拷贝方法,保持兼容),后续重构时可安全清理。
  4. 配置 ESLint 规避倒退:在项目中集成 eslint-plugin-you-dont-need-momentjs,并在代码提交检查(Git Hooks)中禁止再次引入 moment。
原生 TC39 Temporal 规范演进展望: TC39 正在推进全新的标准 JavaScript 日期时间 API —— Temporal。它在 ECMAScript 核心层面彻底解决了 Date 对象的不可变性、夏令时与纳秒精度等问题。目前主流库(包括 date-fns 与 Day.js)均在设计范式上向 Temporal 保持概念对齐。现代项目无论是选用 date-fns 还是 Day.js,未来平移至标准 Temporal 规范的阻力都会非常微小。

六、全维度综合评估总结

综上所述,JavaScript 日期库的选择并不是非此即彼的玄学,而是取决于团队对打包体积敏感度、TypeScript 工程化严谨度与既有代码迁移成本的权衡取舍:

JS日期库选型:Day.js、date-fns与Moment.js对比
图 4:三大日期库全维度综合评估总结矩阵
选型最终落地建议速记:
  • 老项目改造 / 轻量 C 端与移动端 H5:无脑选择 Day.js。极小的体积开销与近乎 100% 兼容的链式 API,能在极短时间内斩获包体积收益。
  • 现代企业级中后台 / 全面拥抱 TypeScript / 函数式架构:坚定选择 date-fns。纯模块化与天然 Tree-shaking 架构,配合无懈可击的类型推导,是支撑长期严谨工程的最佳选择。
  • Moment.js:仅用于维护历史超稳定老系统,坚决不进入任何新建项目。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章