JS中getYear与getFullYear的区别及为何弃用getYear
深入解析JavaScript中Date对象的getYear与getFullYear两个方法的本质区别、计算规则及历史弃用原因,并提供完整的代码迁移与排查指南。
date.getFullYear(),彻底禁用 date.getYear()。getFullYear() 返回的是公历四位绝对年份(如 2026),而早期的 getYear() 返回的是“当前年份减去 1900”的值(如 2026 年返回 126)。由于 getYear() 在跨越 2000 年千禧年时无法表达预期的两位年份,引发了历史上著名的 Y2K 代码灾难及浏览器分歧,ECMAScript 早在 1999 年发布的 ES3 规范中便将其正式废弃并移入遗留附录。
一、getYear 与 getFullYear 的本质区别与运算模型
很多刚接触 JavaScript 的开发者容易望文生义,以为 getYear() 获取的是年份后两位(如将 2026 年误认为 26),而 getFullYear() 获取的是完整四位年份。这种理解在概念层面上是完全错误的。
按照 ECMAScript 规范定义,两者的计算模型有着根本差异:
-
Date.prototype.getFullYear():返回 Date 对象基于本地时间的绝对公历年份(Four-digit Year)。例如 1999 年返回1999,2000 年返回2000,2026 年返回2026。计算结果不依赖任何偏置基数,真实直观。 -
Date.prototype.getYear():返回 Date 对象基于本地时间的年份减去 1900 后的数值。公式恒等于:getYear() = Year - 1900。
这意味着,当且仅当年份处于 1900 年至 1999 年之间时,Year - 1900 的结果才会恰好落在 0 ~ 99 之间,在外观上“碰巧”呈现出类似两位数年份的假象。一旦年份走出这一区间,其返回值便会彻底暴露问题:
| 测试公历年份 | date.getYear() 实际返回值 | date.getFullYear() 实际返回值 | 结果分析 |
|---|---|---|---|
| 1890 年 | -10 (1890 - 1900) |
1890 |
产生负数,常规数字格式化极易直接报错 |
| 1995 年 | 95 (1995 - 1900) |
1995 |
巧合落在两位数范围内,造成“返回后两位”的认知假象 |
| 1999 年 | 99 (1999 - 1900) |
1999 |
最后一年满足两位数外观假象 |
| 2000 年 | 100 (2000 - 1900) |
2000 |
打破两位数假设,输出三位数,代码直接崩解 |
| 2026 年 | 126 (2026 - 1900) |
2026 |
输出 126,既不是 2026,也不是 26,无任何直观业务语义 |
从图 1 可以清楚看出,getYear() 以 1900 年作为原点计算相对位移。在开发中,若在 2026 年写出 date.getYear(),得到的结果是 126。如果开发者以为它返回后两位而直接拼接到页面上(如 "20" + date.getYear()),就会渲染出离奇的 "20126" 年。
二、为何彻底弃用 getYear:从 Y2K 千年虫到浏览器分裂
getYear() 的诞生源于 JavaScript 诞生早期(1995 年 Netscape Navigator 2.0)。当时 Brendan Eich 设计 Date 对象时,大量参考了 C 语言标准库 time.h 中的 struct tm。而在 C 语言中,tm_year 字段原本就是定义为“自 1900 年以来的年数”(years since 1900)。
然而在 Web 脚本普及的 20 世纪 90 年代末,这个设计带来了灾难性的连锁反应:
1. 臭名昭著的字符串拼接错误
在 1999 年以前,大量前端脚本为了展示四位年份,常写出如下代码:
// 1999 年以前广为流传的错误代码示例
var d = new Date();
var yearStr = "19" + d.getYear(); // 在 1998 年输出 "1998",在 1999 年输出 "1999"
当时间指针跳入 2000 年 1 月 1 日时,d.getYear() 返回了 100,上述代码生成的字符串瞬时变成了 "19100"。全球海量网站在千禧年当天版权信息、日历控件全部错乱,成为了 Web 领域最知名的千年虫(Y2K Bug)典型代表。
2. 历史上的早期浏览器兼容性分裂
如果仅仅是返回 100,开发者尚可通过补丁解决,但早期浏览器的分歧让情况雪上加霜:
-
Netscape 阵营:严格遵守 C 语言与早期规范,始终执行
year - 1900。因此 2000 年返回100。 -
微软 Internet Explorer 阵营:IE 4 和早期 IE 5 观察到大量页面显示出 "19100",工程师做出了一个自作聪明的“启发式修补”:当面对 1900~1999 年时返回两位数(即 0~99);而当年份处于 2000 年及以后(或者 1900 年以前)时,直接返回四位数的完整年份(如返回
2000)。
这一分裂导致开发者写出的防错补丁直接两头受击。如果开发者在脚本中写了 var full = 1900 + d.getYear();:
- 在 Netscape 下:
1900 + 100 = 2000,计算正确; - 在 IE 下:
1900 + 2000 = 3900,计算直接穿越到了 3900 年!
3. ECMAScript 的标准化纠偏与 Annex B 降级
面对彻底失控的混乱局面,ECMA 国际在 1999 年 12 月发布的 ECMAScript 第 3 版(ES3) 中作出了决定性裁决:
-
正式推出全新标准 API:引入
Date.prototype.getFullYear()和Date.prototype.setFullYear(),强制规定统一返回四位公历年份,所有合规实现必须严格一致。 -
官方废弃
getYear():在核心语言规范中将getYear()与setYear()标注为 Deprecated(已废弃)。在现代 ECMAScript 规范中,它们被放逐至 Annex B(针对 Web 浏览器的附加遗留特性),仅为了向下兼容 20 世纪的老旧古董网页而保留,并统一锁定为year - 1900。
规范提醒
ECMAScript 规范在 Annex B 中明确声明:Annex B 中定义的所有特性均属于遗留特性,可能存在反直觉或不可靠的行为。任何新编写的 ECMAScript 代码均不应使用这些特性。
三、现代代码改造与全面排查步骤
在现代化前端或 Node.js 服务端工程中,消除 getYear() 不仅是消除告警,更是保障系统日期准确性的底线要求。改造存量项目时,建议遵循以下清晰的 5 个步骤:
-
全局静态检索:定位存量隐患
在工程根目录下使用代码编辑器的全局搜索,或使用终端命令行进行正则匹配:
# 检索所有调用 getYear 和 setYear 的源码文件 grep -rnE "(getYear|setYear)\s*\(" ./src重点排查历史悠久的工具库(utils)、模板引擎注入、老旧报表计算或未更新的第三方插件。
-
标准替换:升级为 FullYear 系列方法
将读取方法
getYear()整体替换为getFullYear();同时将写入方法setYear()整体替换为setFullYear():// ❌ 错误且已废弃的旧写法 const oldYear = date.getYear(); date.setYear(2026); // ✅ 标准现代写法 const currentYear = date.getFullYear(); date.setFullYear(2026); -
清除历史防虫“补丁”:避免二次偏置(关键陷阱)
在修改历史代码时,务必检查紧随其后的上下文。老旧代码常常包含诸如
year < 1000 ? year + 1900 : year或year + 1900之类的逻辑。在将getYear()替换为getFullYear()后,如果不移除这些加法补丁,将会再次算出 3900+ 年的荒谬数值:// ❌ 遗留补丁未清除导致的二次故障 const year = date.getFullYear(); // 已返回 2026 const fixedYear = year + 1900; // 结果变成了 3926! // ✅ 彻底删除历史冗余逻辑 const finalYear = date.getFullYear(); // 直接使用 2026 即可 -
时区语义核对:本地时间 vs 世界协调时 (UTC)
getFullYear()获取的是运行环境本地时区的年份。对于绝大多数 UI 展示与常规业务,使用本地时间是恰当的;但在处理跨时区数据同步、服务端日志解析或金融账期计算时,如果日期字符串是 ISO UTC 格式(如2025-12-31T23:30:00Z在北京时间东八区会是 2026 年),请明确是否应当使用getUTCFullYear():// 本地时间年份(依赖客户端机器时区) const localYear = date.getFullYear(); // 世界标准时间年份(UTC 时区) const utcYear = date.getUTCFullYear(); -
配置自动化 Lint 规则:建立持续防护门禁
为了杜绝团队新成员在无意中再次敲入
getYear(),应在 ESLint 配置文件中加入静态规则拦截。例如通过no-restricted-properties规则在编译与提交阶段阻断:// .eslintrc.js 配置示例 module.exports = { rules: { 'no-restricted-properties': [ 'error', { object: 'Date', property: 'getYear', message: '禁止使用已废弃的 Date.prototype.getYear(),请使用 getFullYear() 替代。' }, { property: 'getYear', message: '请使用 getFullYear() 代替已废弃的 getYear()。' }, { property: 'setYear', message: '请使用 setFullYear() 代替已废弃的 setYear()。' } ] } };
四、全要素决策速查与知识总结
为了便于日常查阅与快速决策,下表总结了 getYear() 与 getFullYear() 在核心技术维度的全方位对照:
| 对比维度 | Date.prototype.getYear() | Date.prototype.getFullYear() |
|---|---|---|
| 规范地位 | ECMAScript 3 弃用,现收录于 Annex B 遗留附录 | ECMAScript 3+ 正式核心标准规范 |
| 计算公式 | Year - 1900 |
绝对公历年份数值 |
| 1999 年返回值 | 99 |
1999 |
| 2000 年返回值 | 100 (现代规范) |
2000 |
| 2026 年返回值 | 126 |
2026 |
| 配套修改方法 | date.setYear(val)(同样废弃) |
date.setFullYear(year, [month], [date]) |
| 对应 UTC 方法 | 无 | date.getUTCFullYear() |
| 工程使用建议 | 绝对禁止使用,存量代码全面清除 | 全场景标准首选 |
工程总结口诀
在 JavaScript 中获取年份时,请牢记:只要获取年份,唯一正确的 API 只有 getFullYear()(或跨时区场景下的 getUTCFullYear())。忘记 getYear(),将其永远留在计算机历史档案中,是保证代码远离日期奇特故障的最简单方式。
Chrome DevTools JS 调试入门:断点设置与单步执行
2026-11-20 22:04:46
JS递归遍历树形结构的实现原理与代码示例
2026-11-20 19:47:56
JS密码正则表达式:同时包含大小写、数字和特殊字符的写法
2026-11-20 19:45:23
ES6+新特性:JavaScript函数默认参数与剩余参数的用法
2026-11-20 19:17:28
JS使用Object.assign和展开运算符实现对象浅拷贝
2026-11-20 18:26:00








