JavaScript日期处理库Day.js与date-fns怎么选

一、为什么原生 Date 难以满足复杂需求

JavaScript 原生内置的 Date 对象长期存在 API 设计不直观、月份从 0 开始计数、解析行为跨浏览器不一致以及缺少开箱即用的格式化等问题。最关键的是，原生 Date 的多数修改操作（如 setDate）是破坏原对象的（Mutable），在多人协作或状态流转中容易引发隐蔽的副作用。

早年社区普遍采用 Moment.js 解决这些痛点，但随着前端工程化对首屏加载性能与模块化要求的提高，Moment.js 因包体积过大（未压缩且带多语言时超 60KB）且架构无法支持 Tree-shaking，已被其官方团队宣布进入维护状态。现代前端开发中，Day.js 与 date-fns 成为了当下替代 Moment 的两大主流选择。

二、架构哲学与 API 风格对比

虽然两者的目标都是提供可靠且不可变（Immutable）的日期处理能力，但它们的底层设计哲学截然不同：

• Day.js：面向对象与包装器模式。它将日期包装为专有的 Day.js 对象，完整复刻了 Moment.js 的链式语法（如 dayjs().add(7, 'day').format('YYYY-MM-DD')）。只要用过 Moment.js，基本可以实现无缝迁移。
• date-fns：函数式编程与原生对象穿透。它被称为“日期领域的 lodash”。所有工具均以独立纯函数的形式输出，输入通常是原生 Date、数字时间戳或特定字符串，输出也是原生 Date 或对应结果，中间不存在任何中间包装实例。

三、体积构成与 Tree-shaking 打包机制

在衡量包体积时，不能只看主页标注的最小体积，还需要结合生产构建中的实际使用场景：

• Day.js 的体积模式（核心极小 + 显式插件扩展）：Day.js 默认核心仅约 2KB（Gzip），包含了最常用的解析、常用格式化和加减运算。对于高级特性（如时区转换 timezone、UTC 支持 utc、相对时间 relativeTime 等），需要显式引入插件并调用 dayjs.extend()。这种模式对无需复杂功能的小型网页极其友好。
• date-fns 的体积模式（零内核底座 + 模块级 Tree-shaking）：date-fns 本身没有固定的“底座”，每个方法都以独立 ES 模块方式发布。如果你在页面中只用了 format 和 addDays，现代打包器（如 Webpack、Vite、Rollup）只会打包这两个函数及其直接依赖的代码（仅约数百字节至几KB），完全剔除其余几百个未使用的函数。

四、关键场景代码实现与语法差异

为了让选择更具实操性，我们通过解析、格式化、日期增减运算和国际化等典型业务场景，对比两者的实际编码差异。

1. 日期解析与格式化

格式化是前端最常见的任务。需要注意的是两者的格式化占位符存在细微标准差异：Day.js 采用 Moment 兼容的格式（年份为大写 YYYY，日为大写 DD），而 date-fns 严格遵循 Unicode 标准规范（年份为小写 yyyy，日为小写 dd）。

// === Day.js 格式化 ===
import dayjs from 'dayjs';

const now = dayjs('2026-10-24T14:30:00');
const formattedDayjs = now.format('YYYY-MM-DD HH:mm:ss');
console.log(formattedDayjs); // 2026-10-24 14:30:00

// === date-fns 格式化 ===
import { format, parseISO } from 'date-fns';

const date = parseISO('2026-10-24T14:30:00');
const formattedFns = format(date, 'yyyy-MM-dd HH:mm:ss');
console.log(formattedFns); // 2026-10-24 14:30:00

2. 日期计算与链式操作

当需要连续进行多步运算时（例如：获取 7 天后的日期，并定位到当天的最后一秒）：

// === Day.js 链式调用 ===
import dayjs from 'dayjs';

const targetDay = dayjs()
  .add(7, 'day')
  .endOf('day')
  .format('YYYY-MM-DD HH:mm:ss');

// === date-fns 函数嵌套或组合 ===
import { addDays, endOfDay, format } from 'date-fns';

// 方式一：嵌套调用
const targetFns = format(endOfDay(addDays(new Date(), 7)), 'yyyy-MM-dd HH:mm:ss');

// 方式二：配合函数式 pipe 组合（如 lodash/flow 或 native compose）
// const getNextTarget = flow(d => addDays(d, 7), endOfDay, d => format(d, 'yyyy-MM-dd HH:mm:ss'));

从代码可读性来看，如果是单纯的连续运算，Day.js 的点语法链式调用直观流畅，符合多数前端的线性思考方式；而 date-fns 采用纯函数传参，无状态包装，更适合配合现代流式操作或管道函数处理。

3. 时区（Timezone）与本地化处理

跨时区系统处理是日期计算中的重头戏：

• Day.js 时区处理：需要显式载入 utc 和 timezone 两个插件。配置后，可以使用 dayjs.tz(date, 'Asia/Shanghai') 统一处理。
• date-fns 时区处理：date-fns 官方提供了配套的 @date-fns/tz 或社区广泛使用的 date-fns-tz 包，利用原生 Intl API 实现轻量时区映射，无需打包沉重的时区全量数据库文件。

五、选型与迁移落地实施步骤

无论是新项目立项还是对旧有 Moment.js 项目进行瘦身改造，选型与实施建议按以下四个步骤稳步推进：

六、选型决策矩阵与场景指南

为了让决策更具针对性，下面从核心指标、心智模型、开发体验及工程约束四个维度进行综合对比：

七、常见陷阱与注意事项

1. Day.js 插件未注册导致运行时报错： 由于 Day.js 核心默认不包含扩展插件，如果在未调用 dayjs.extend(utc) 的情况下直接调用 dayjs.utc()，会在运行时直接抛出 TypeError: dayjs(...).utc is not a function。建议在项目入口文件（如 main.js 或统一的工具层 date.js）中一次性挂载所有业务所需插件。
2. date-fns 解构导入与 CommonJS 混用陷阱： 虽然 date-fns 具备优秀的 Tree-shaking 特性，但如果项目的 Babel 或打包配置将 ES 模块转译为 CommonJS 规范，Tree-shaking 可能会失效。务必确保现代打包器配置保留了 ES 模块静态导入语法。
3. 原生 Temporal API 的前瞻视角： ECMAScript 规范正在推进全新的原生 Temporal API，旨在从语言核心层面彻底解决时区、精度与不可变性问题。但目前在生产环境中仍需要 Polyfill 支持。在 Temporal 获得各大运行环境全面原生支持之前，Day.js 与 date-fns 依然是当前生产环境中最稳健、最可靠的日期解决方案。