Day.js

一个仅 2KB 的极轻量 JavaScript 日期时间库，拥有与 Moment.js 高度兼容的 API。

技术简介说明

Day.js 是一个极简主义的 JavaScript 日期时间处理库，设计目标是在保持与 Moment.js API 高度兼容的同时，将核心包体积控制在约 2KB（minified + gzipped）。它解决了 Moment.js 体积庞大、不可 tree-shaking 的问题，同时保留了开发者熟悉的链式调用体验。

Day.js 的核心理念是"即用即走"——不可变对象（Immutable）设计让日期操作更安全，不会意外修改原始对象。所有格式化、解析、计算操作都返回新的 Day.js 实例，避免了 Moment.js 中常见的可变性陷阱。

Day.js 采用插件架构，核心功能保持精简，时区处理、国际化、相对时间等高级功能按需加载。这种设计使其在 bundle size 敏感的现代前端项目（尤其是移动端和 SSR 场景）中极具竞争力。

基本信息

快速上手

安装

# npm
npm install dayjs
 
# yarn
yarn add dayjs
 
# pnpm
pnpm add dayjs
 
# CDN
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
<!-- 如需中文 locale -->
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/zh-cn.js"></script>

基础配置

import dayjs from 'dayjs'
 
// 引入并注册插件
import advancedFormat from 'dayjs/plugin/advancedFormat'
import 'dayjs/locale/zh-cn'
 
dayjs.extend(advancedFormat)
dayjs.locale('zh-cn') // 全局设置为中文

最小示例

import dayjs from 'dayjs'
 
// 解析当前时间
const now = dayjs()
 
// 格式化
console.log(now.format('YYYY-MM-DD HH:mm:ss')) // '2026-07-07 14:30:00'
 
// 日期计算
const tomorrow = now.add(1, 'day')
const lastMonth = now.subtract(1, 'month')
 
// 相对时间（需要 relativeTime 插件）
import relativeTime from 'dayjs/plugin/relativeTime'
dayjs.extend(relativeTime)
console.log(now.subtract(2, 'hour').fromNow()) // '2 hours ago'

核心概念与架构

不可变性（Immutability）

Day.js 的所有操作都返回新实例，原始对象永远不会被修改。这与 Moment.js 的可变设计形成鲜明对比：

const a = dayjs('2026-01-01')
const b = a.add(1, 'day')
// a 保持不变，b 是新的实例
console.log(a.format('YYYY-MM-DD')) // '2026-01-01'
console.log(b.format('YYYY-MM-DD')) // '2026-01-02'

插件架构

Day.js 核心只包含最基本的日期操作，所有扩展功能通过插件按需加载：

• 插件在调用前必须通过 dayjs.extend() 注册
• 插件只需注册一次，全局生效
• 插件可以链式调用

Moment.js 兼容性

Day.js 刻意保持与 Moment.js API 的高度兼容，大部分 Moment.js 代码可以几乎无缝迁移到 Day.js。但注意，Day.js 并非 100% 复制 Moment.js 的所有行为，一些已知的边缘情况差异在文档中有详细说明。

核心特性

• 极小体积：核心包仅约 2KB（minified + gzipped），远小于 Moment.js（~72KB）
• 不可变设计：所有操作返回新实例，避免副作用
• Moment.js 兼容 API：学习成本极低，迁移成本小
• 插件系统：30+ 官方插件按需加载，覆盖时区、国际化、日历、持续时间等场景
• 完整的 I18n 支持：支持 160+ 种语言/locale
• 浏览器 + Node.js：同时支持浏览器环境和 Node.js 环境
• TypeScript 支持：提供完整的 TypeScript 类型定义
• 链式调用：流畅的 API 设计，支持 dayjs().add(1, 'day').format('YYYY-MM-DD')

生态图

核心插件

第三方生态

• dayjs-plugin-globalize：与 Globalize 集成
• dayjs-range：日期范围选择辅助
• dayjs-business-days：工作日计算

关键依赖

Day.js 核心零依赖，插件利用浏览器原生 Intl API 实现时区和国际化功能，无需引入额外的时区数据文件。

适用场景

• 移动端 Web 应用：2KB 的体积使其对包大小敏感的移动场景非常友好
• 快速原型开发：Moment.js 兼容的 API 让熟悉 Moment.js 的开发者可以零学习成本上手
• 轻量级日期格式化：简单的日期显示和格式化场景
• SSR / 边缘计算：小体积意味着更快的冷启动和更低的内存占用
• 从 Moment.js 迁移：API 高度兼容，是 Moment.js 项目迁移到轻量方案的理想过渡选择
• CDN 加载：2KB 的体积通过 CDN 加载几乎无感
• IE11 兼容项目：Day.js 支持 IE11（需 polyfill），适合需要兼容旧浏览器的项目

开发与工程化

项目构建

# 克隆项目
git clone https://github.com/iamkun/dayjs.git
cd dayjs
 
# 安装依赖
npm install
 
# 运行测试
npm run test
 
# 构建
npm run build

开发最佳实践

• 按需引入插件：只加载实际使用的插件，保持 bundle 最小化
• Locale 优化：只引入项目需要的 locale，避免加载全部 160+ 种语言
• CI/CD 集成：Day.js 自身使用 Jest 进行测试，支持 GitHub Actions

与构建工具集成

// Webpack / Vite 按需加载 locale
import dayjs from 'dayjs'
import zh from 'dayjs/locale/zh-cn'
import en from 'dayjs/locale/en'
 
// 只注册需要的 locale
dayjs.locale(zh)

性能与安全

性能特点

• 解析速度：与 Moment.js 相当，部分场景略快
• 内存占用：由于不可变设计，每次操作都会创建新实例，高频操作场景需注意内存分配
• Bundle 影响：核心 2KB，单个插件通常 1KB 以下，tree-shaking 表现优于 Moment.js

优化建议

• 避免在循环中频繁创建 Day.js 实例
• 只注册必要的插件和 locale
• 对于大量日期计算，考虑缓存中间结果

安全注意事项

• Day.js 纯前端日期处理，不涉及网络请求，攻击面小
• 用户输入的日期字符串应进行校验，避免 XSS
• 定期更新至最新版本以获取安全补丁

技术对比

何时选择 Day.js

• 从 Moment.js 迁移，希望最小化代码改动
• 对 bundle size 有严格要求
• 团队已熟悉 Moment.js API
• 需要快速集成的轻量日期处理

最佳实践

推荐模式

// ✅ 集中管理插件注册
// utils/dayjs.js
import dayjs from 'dayjs'
import timezone from 'dayjs/plugin/timezone'
import utc from 'dayjs/plugin/utc'
import 'dayjs/locale/zh-cn'
 
dayjs.extend(utc)
dayjs.extend(timezone)
dayjs.locale('zh-cn')
dayjs.tz.setDefault('Asia/Shanghai')
 
export default dayjs
 
// ✅ 在其他模块中直接引用
import dayjs from '@/utils/dayjs'

常见陷阱

• 忘记注册插件：使用高级格式化 token 或时区功能前，必须先 extend 对应插件
• 时区数据：Day.js 的 timezone 插件依赖浏览器 Intl API，IE11 需要额外 polyfill
• Locale 全局影响：dayjs.locale() 是全局设置，多语言应用建议使用 dayjs().locale() 实例级别设置
• Day.js 2.0 开发中：注意关注 v2 alpha 版本的 breaking changes

技术局限与边界

• Tree-shaking 支持有限：由于插件架构设计，Day.js 的插件无法被 tree-shaking，即使只用了某个插件的一个功能，整个插件都会被打包
• 无内置时区数据：timezone 插件依赖浏览器 Intl API，不支持自定义时区数据
• Day.js 2.0 不确定性：v2 仍在 alpha 阶段，正式发布时间和 breaking changes 尚不明确
• 功能覆盖面有限：相比 Luxon 和 date-fns，Day.js 的高级日期操作（如复杂 duration 计算、ISO 8601 周计算等）需要额外插件
• 不适合复杂业务逻辑：对于涉及大量日历计算、排班、recurring events 的复杂场景，Day.js 可能需要大量插件组合

学习资源

• 官方文档：https://day.js.org/docs/en/install/install
• GitHub 仓库：https://github.com/iamkun/dayjs
• 掘金教程：https://juejin.cn/post/7223182095584182328
• Cheat Sheet：https://javascript.plainenglish.io/mastering-day-js-the-ultimate-cheat-sheet-eabc984b4c85
• Stack Overflow：搜索 dayjs 标签获取社区问答

2026 年现状

当前版本

• 稳定版：v1.11.21（2026 年 5 月发布），持续进行 bug 修复和 locale 更新
• 开发版：v2.0.0-alpha.4 正在开发中，预计会有 breaking changes

社区活跃度

• GitHub Stars 46,000+，npm 周下载量 1,500 万+
• 维护节奏以 bug 修复和 locale 更新为主，新功能开发较少
• 社区贡献活跃，插件生态持续丰富

发展趋势

• Day.js 在轻量级日期库市场保持稳固地位，是 Moment.js 迁移的首选轻量替代
• 随着 Temporal API 浏览器原生支持的推进（Chrome 144+、Firefox 139+），Day.js 作为"轻量 Moment 替代"的定位可能会逐步向"Temporal 过渡层"演进
• v2.0 的发布将是重要里程碑，预计会改善 tree-shaking 支持并引入更多现代特性
• 在 date-fns v4/v5 和 Luxon 3.x 的竞争下，Day.js 的核心优势仍然是极致的轻量体积和 Moment.js 兼容性