JS中getYear与getFullYear的区别及为何弃用getYear

作者:代码拾荒时间:2026-11-21 09:56:10浏览:647

深入解析JavaScript中Date对象的getYear与getFullYear两个方法的本质区别、计算规则及历史弃用原因,并提供完整的代码迁移与排查指南。

在 JavaScript 中获取年份时,核心结论非常明确:必须始终使用 date.getFullYear(),彻底禁用 date.getYear()。getFullYear() 返回的是公历四位绝对年份(如 2026),而早期的 getYear() 返回的是“当前年份减去 1900”的值(如 2026 年返回 126)。由于 getYear() 在跨越 2000 年千禧年时无法表达预期的两位年份,引发了历史上著名的 Y2K 代码灾难及浏览器分歧,ECMAScript 早在 1999 年发布的 ES3 规范中便将其正式废弃并移入遗留附录。
JS中getYear与getFullYear的区别及为何弃用getYear
核心对照缩略图:getYear() 返回“年份 - 1900”而已被弃用,getFullYear() 返回完整四位年份为官方推荐规范

一、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,无任何直观业务语义
JS中getYear与getFullYear的区别及为何弃用getYear
图 1:getYear 与 getFullYear 的计算原理与典型年份映射轴,揭示 1900~1999 两位数假象与 2000 年断裂点

从图 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 年!
JS中getYear与getFullYear的区别及为何弃用getYear
图 2:Y2K 千年虫机理与历史浏览器行为分歧演进图,详细还原“19100年”与“3900年”的事故成因

3. ECMAScript 的标准化纠偏与 Annex B 降级

面对彻底失控的混乱局面,ECMA 国际在 1999 年 12 月发布的 ECMAScript 第 3 版(ES3) 中作出了决定性裁决:

  1. 正式推出全新标准 API:引入 Date.prototype.getFullYear() 和 Date.prototype.setFullYear(),强制规定统一返回四位公历年份,所有合规实现必须严格一致。
  2. 官方废弃 getYear():在核心语言规范中将 getYear() 与 setYear() 标注为 Deprecated(已废弃)。在现代 ECMAScript 规范中,它们被放逐至 Annex B(针对 Web 浏览器的附加遗留特性),仅为了向下兼容 20 世纪的老旧古董网页而保留,并统一锁定为 year - 1900。

规范提醒

ECMAScript 规范在 Annex B 中明确声明:Annex B 中定义的所有特性均属于遗留特性,可能存在反直觉或不可靠的行为。任何新编写的 ECMAScript 代码均不应使用这些特性。

三、现代代码改造与全面排查步骤

在现代化前端或 Node.js 服务端工程中,消除 getYear() 不仅是消除告警,更是保障系统日期准确性的底线要求。改造存量项目时,建议遵循以下清晰的 5 个步骤:

JS中getYear与getFullYear的区别及为何弃用getYear
图 3:存量代码排查与全面改造五步流程(搜索、替换、清旧补丁、时区校验、静态守卫)
  1. 全局静态检索:定位存量隐患

    在工程根目录下使用代码编辑器的全局搜索,或使用终端命令行进行正则匹配:

    # 检索所有调用 getYear 和 setYear 的源码文件
    grep -rnE "(getYear|setYear)\s*\(" ./src

    重点排查历史悠久的工具库(utils)、模板引擎注入、老旧报表计算或未更新的第三方插件。

  2. 标准替换:升级为 FullYear 系列方法

    将读取方法 getYear() 整体替换为 getFullYear();同时将写入方法 setYear() 整体替换为 setFullYear():

    // ❌ 错误且已废弃的旧写法
    const oldYear = date.getYear();
    date.setYear(2026);
    
    // ✅ 标准现代写法
    const currentYear = date.getFullYear();
    date.setFullYear(2026);
  3. 清除历史防虫“补丁”:避免二次偏置(关键陷阱)

    在修改历史代码时,务必检查紧随其后的上下文。老旧代码常常包含诸如 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 即可
  4. 时区语义核对:本地时间 vs 世界协调时 (UTC)

    getFullYear() 获取的是运行环境本地时区的年份。对于绝大多数 UI 展示与常规业务,使用本地时间是恰当的;但在处理跨时区数据同步、服务端日志解析或金融账期计算时,如果日期字符串是 ISO UTC 格式(如 2025-12-31T23:30:00Z 在北京时间东八区会是 2026 年),请明确是否应当使用 getUTCFullYear():

    // 本地时间年份(依赖客户端机器时区)
    const localYear = date.getFullYear();
    
    // 世界标准时间年份(UTC 时区)
    const utcYear = date.getUTCFullYear();
  5. 配置自动化 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() 在核心技术维度的全方位对照:

JS中getYear与getFullYear的区别及为何弃用getYear
图 4: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(),将其永远留在计算机历史档案中,是保证代码远离日期奇特故障的最简单方式。

作者最新文章
相关文章
更多