dayjs 和 date-fns 中获取当前年份的代码示例

作者:闭包旅人

时间:2026-11-17

浏览:474

详细讲解在 dayjs 与 date-fns 中获取当前年份的完整代码示例,涵盖数值类型与字符串格式化提取方法、设计架构差异、YYYY 与 yyyy 的跨年占位符陷阱排查及工程选型建议。

文章目录
在现代 JavaScript 与 TypeScript 项目开发中,若需获取当前年份,dayjs 与 date-fns 提供了截然不同却各自清晰的 API 设计:使用 dayjs 可以通过 dayjs().year() 获取数字类型年份,或使用 dayjs().format('YYYY') 获取格式化字符串;而在 date-fns 中,则通过纯函数 getYear(new Date()) 提取数字年份,或调用 format(new Date(), 'yyyy') 得到字符串年份。下文将完整展示两者的代码示例、工程配置、架构差异及不可忽视的跨年占位符陷阱。
dayjs 和 date-fns 中获取当前年份的代码示例
缩略图:dayjs 与 date-fns 获取当前年份核心方案对比

一、核心结论与快速代码对照

获取年份的需求通常细分为两类:一类用于年龄计算、跨度统计等业务逻辑运算,需要 number 数值类型;另一类用于页面版权宣告(如 © 2026)、表单回显或报表导出,需要 string 字符串类型。

以下是两个库在处理这两种场景时最直接的代码对照:

// 1. dayjs 方案
import dayjs from 'dayjs';

const currentYearNum = dayjs().year();          // 2026 (数值类型)
const currentYearStr = dayjs().format('YYYY');  // "2026" (字符串类型)

// 2. date-fns 方案
import { getYear, format } from 'date-fns';

const dateFnsYearNum = getYear(new Date());         // 2026 (数值类型)
const dateFnsYearStr = format(new Date(), 'yyyy');   // "2026" (字符串类型,注意小写 yyyy)
dayjs 和 date-fns 中获取当前年份的代码示例
图 1:从依赖引入到消费年份的四步执行流程图

二、在 dayjs 中获取当前年份的具体实践

dayjs 是一个极轻量级的日期时间库,设计上深度兼容 Moment.js 的链式语法体系,其核心代码打包体积仅约 2KB。在 dayjs 的模型中,调用 dayjs() 时若不传任何参数,默认会以当前的本地客户端时间创建一个不可变的 Dayjs 包装对象。

1. 安装与模块导入

在项目中通过包管理器安装 dayjs:

npm install dayjs
# 或者使用 pnpm / yarn
pnpm add dayjs

在业务代码中根据工程环境选择导入方式:

// ES 模块规范 (ESM / Vite / Webpack / Next.js)
import dayjs from 'dayjs';

// CommonJS 规范 (Node.js 传统环境)
const dayjs = require('dayjs');

2. 获取数字型年份:dayjs().year()

.year() 方法是 Dayjs 实例上的原生 Getter/Setter 方法。当不传实参时,它执行 Getter 行为,返回一个 4 位数的整数:

// 获取当前时间的年份整数
const year = dayjs().year();

console.log(year);        // 输出示例:2026
console.log(typeof year); // 输出:"number"

// 等价用法:使用通用 get 方法
const sameYear = dayjs().get('year'); // 2026

在实现上,dayjs().year() 本质上调用了包装在内部的原生 Date.prototype.getFullYear(),因此其返回值与运行环境的本地时区保持完全一致。

3. 获取字符串格式化年份:dayjs().format('YYYY')

当需要在界面上展示文本或拼接日历前缀时,推荐使用 .format() 函数:

// 仅提取 4 位年份字符串
const yearString = dayjs().format('YYYY');
console.log(yearString);        // 输出示例:"2026"
console.log(typeof yearString); // 输出:"string"

// 提取 2 位简短年份(例如 26)
const shortYear = dayjs().format('YY');
console.log(shortYear);         // 输出示例:"26"

// 在页面页脚版权中动态渲染
const copyrightText = `Copyright © ${dayjs().format('YYYY')} Inc.`;
console.log(copyrightText);     // 输出:"Copyright © 2026 Inc."
dayjs 和 date-fns 中获取当前年份的代码示例
图 2:面向对象包装模型与纯函数式树摇管道的架构区别

三、在 date-fns 中获取当前年份的具体实践

与 dayjs 不同,date-fns 并不提供全局的大对象包装,而是将各个日期操作设计为一组功能单一、互相独立的纯函数。它直接操作 JavaScript 原生 Date 实例,因而在现代支持 Tree-shaking 的构建工具中能够实现极高的打包精简度。

1. 安装与按需导入

安装 date-fns(推荐使用 v3 及以上版本):

npm install date-fns
# 或者使用 pnpm / yarn
pnpm add date-fns

通过解构语法按需引入所需函数,打包工具会自动剔除未被引用的数百个其他日期函数:

// 推荐用法:按需引入核心函数
import { getYear, format } from 'date-fns';

// 针对不支持命名导出的旧环境,可直接从子路径导入
// import getYear from 'date-fns/getYear';

2. 获取数字型年份:getYear(new Date())

getYear 函数接收一个日期对象并返回对应的年份数字。注意,date-fns 不会自动生成当前时间,必须显式传入 new Date():

// 显式传入当前原生 Date 对象
const now = new Date();
const currentYear = getYear(now);

console.log(currentYear);        // 输出示例:2026
console.log(typeof currentYear); // 输出:"number"

3. 获取字符串格式化年份:format(new Date(), 'yyyy')

使用 date-fns 的 format 函数可以将当前时间格式化为指定文本结构:

const now = new Date();

// 获取 4 位日历年份字符串(注意:必须是全小写 yyyy)
const formattedYear = format(now, 'yyyy');
console.log(formattedYear);        // 输出示例:"2026"
console.log(typeof formattedYear); // 输出:"string"

// 获取 2 位简短年份(小写 yy)
const shortYear = format(now, 'yy');
console.log(shortYear);            // 输出示例:"26"
dayjs 和 date-fns 中获取当前年份的代码示例
图 3:跨年高频故障 —— YYYY 与 yyyy 的底层规范与跨年计算差异

四、关键陷阱:格式化占位符 YYYY 与 yyyy 的致命差异

在日常业务开发中,开发者在从 dayjs 切换到 date-fns(或者混合使用两者)时,最常踩到的暗坑就是占位符的大小写定义。如果在 date-fns 中习惯性地使用大写 YYYY,会在每年 12 月底或 1 月初引发极其隐蔽的线上故障。

⚠️ 跨年警报:在 date-fns 中,小写 yyyy 代表常规日历年(Calendar Year),而大写 YYYY 代表 ISO 周纪年份(Week-numbering year)。若在 2025 年 12 月 31 日调用 format(new Date(2025, 11, 31), 'YYYY'),计算出的年份将是 "2026",导致提早整整一年!

造成这种差异的根本原因在于两个库所遵循的规范体系不同:

  • dayjs 采用 Moment 占位符规范:规定 YYYY 表示 4 位公历年(Calendar Year),这是绝大多数开发者最熟悉的直觉写法。在 dayjs 中,若误写为小写 yyyy,由于它不识别该 token,会直接原样输出字符 "yyyy"。
  • date-fns 严格遵循 Unicode 技术标准(LDML):标准规定小写 y / yyyy 才是普通日历年份;大写 Y / YYYY 被专门保留给基于 ISO 8601 周数的年份计算。在 ISO 规则中,一年的第一周是包含该年 4 天及以上的新周。如果 12 月最后几天恰好与新年的第一周重叠,该周将被视为新年的第 1 周,其 YYYY 将直接跃迁至下一年。

以下代码清楚地展示了这种异常表现:

import { format } from 'date-fns';

// 构造一个处于跨年交叉周的日期:2025年12月30日(周二)
const crossYearDate = new Date(2025, 11, 30);

// 正确写法:使用小写 yyyy
console.log(format(crossYearDate, 'yyyy-MM-dd')); // "2025-12-30" (符合业务预期)

// 错误写法:误用大写 YYYY
console.log(format(crossYearDate, 'YYYY-MM-dd')); // "2026-12-30" (严重故障:年份超前)
dayjs 和 date-fns 中获取当前年份的代码示例
图 4:dayjs 与 date-fns 年份获取技术规格速查与选型决策

五、综合对比与工程选型建议

为了方便在实际项目中根据架构需求进行技术决策,下面整理了两个库在获取当前年份及相关日常操作中的横向比对:

对比项 dayjs date-fns
核心设计哲学 面向对象链式封装,API 高度对齐 Moment.js 函数式编程,零封装开销,直接操作原生 Date
获取年份数字 dayjs().year() getYear(new Date())
格式化年份文本 dayjs().format('YYYY')(大写) format(new Date(), 'yyyy')(小写)
当前时间缺省能力 内置。dayjs() 默认生成当前时间 无内置状态。必须显式传入 new Date()
打包体积表现 固定核心体积约 2KB(Gzip) 完全支持 Tree-shaking,按需引入几十字节
TypeScript 支持 提供完整类型声明文件,易用度高 原生强类型,严格校验原生 Date 与参数合法性

选型建议:

  1. 选择 dayjs 的场景:如果你的团队正在将旧的 Moment.js 项目进行瘦身迁移,或者业务中需要频繁进行诸如 dayjs().startOf('year').add(1, 'month').format(...) 这类多步链式计算,dayjs 能够提供最顺畅、符合直觉的书写体验。
  2. 选择 date-fns 的场景:如果你的项目属于对首屏资源体积控制极其严苛的前端应用、微前端子模块,或者整体代码架构基于纯函数风格构建,date-fns 能够最大化利用打包工具的摇树优化能力,避免引入任何多余代码。

六、常见问题与边界细节

1. 为什么不直接使用原生 JavaScript 的 getFullYear()?

原生 JavaScript 提供了 new Date().getFullYear(),如果你的项目中仅仅只有获取当前年份一个需求,完全不需要安装任何第三方日期库,直接使用原生 API 是性能最好、体积为零的最佳方案。

之所以引入 dayjs 或 date-fns,是因为实际项目中通常伴随着更复杂的日期解析、多语言本地化、时区切换、跨月计算和统一格式化需求。在已有库的工程中,保持统一的日期处理调用方式能够提升团队代码的一致性。

2. 时区差异对“当前年份”判定的影响

无论是 dayjs() 还是 new Date(),默认获取的都是执行代码机器上的本地操作系统时间。在跨年那一刻(例如 12 月 31 日 23:59:59),北京时间(UTC+8)已经进入新年,而伦敦时间(UTC+0)依然属于上一年。

如果服务端日志或跨国业务要求统一按 UTC 判定年份,两个库的处理方式如下:

// dayjs: 需引入 utc 插件
import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
dayjs.extend(utc);

const utcYear = dayjs.utc().year();

// 原生 Date 与 date-fns: 原生自带 getUTCFullYear
const nativeUtcYear = new Date().getUTCFullYear();
💡 最佳实践建议:在编写需要获取年份的单元测试时,尽量避免直接在断言中依赖动态的 dayjs().year(),建议通过依赖注入传入时间基准,或使用类似 Jest 提供的 jest.useFakeTimers().setSystemTime(...) 固定时间点,防止测试用例在跨年夜出现意外失败。

实用工具推荐

电子包浆

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

使用 ›
图片压缩

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

使用 ›
相关文章