时间处理是前端开发中绕不开的一个基本功。无论是列表展示创建时间、活动倒计时、订单超时判断还是图表里的时间轴底层都离不开 JavaScript 的时间函数。很多初学者在刚接触Date对象时会被「时间戳」「UTC」「本地时间」这些概念绕晕写日期格式化时又总是忘记了getMonth()从 0 开始这种细节。本文将系统梳理 JavaScript 中时间函数的核心知识点从时间在计算机中的存储方式出发逐步拆解Date对象的创建、取值、计算、格式化最后通过完整的实战案例演示日期格式化工具函数和倒计时的实现。无论你是刚入门的前端新手还是想查漏补缺的开发者这篇文章都能帮你把时间函数彻底搞懂。1. 时间函数到底在解决什么问题1.1 先从“时间到底是什么”说起要理解时间函数先要理解计算机如何表示时间。我们平时说“2024 年 6 月 1 日 14:30:00”这是一种面向人的时间表示它包含年、月、日、时、分、秒还隐含了时区信息。比如北京时间是 UTC8如果你把这个时间发送给一个在伦敦的用户他看到的本地时间应该是2024-06-01 07:30:00。但计算机不能直接存储这种复杂的表示。它需要一个唯一且确定的数字来标识某个瞬间这个数字就是时间戳。在 JavaScript 中时间戳指的是从 1970 年 1 月 1 日 00:00:00 UTC协调世界时开始到指定时间所经过的毫秒数。换句话说JavaScript 的时间戳是一个毫秒级的整数。// 当前时间的时间戳毫秒 console.log(Date.now()); // 输出示例1717223400000这个数字是全球统一的不管你在北京、纽约还是伦敦同一时刻调用Date.now()得到的数值几乎是一样的严格来说取决于系统时钟是否同步。1.2 时间函数的核心职责时间函数要处理的核心问题可以概括为三件事核心问题具体含义典型场景时间的读取从时间戳中取出年月日时分秒渲染列表时间、显示当前日期时间的计算对时间进行加减、求差值倒计时、订单过期判断、计算年龄时间的格式化将时间对象转成指定格式的字符串日志输出、接口返回、图表横轴显示JavaScript 通过内置的Date对象提供这些能力。虽然Date对象的历史 API 设计有些别扭但掌握它仍然是深入学习dayjs、date-fns等时间库的基础。1.3 UTC、GMT 与本地时间的关系这三个概念经常被混用简单区分一下UTC协调世界时是目前国际通用的时间标准可以理解为“世界统一时间”。GMT格林尼治标准时间曾是时间基准现在一般与 UTC 等价使用。本地时间由操作系统时区决定的时间例如中国是 UTC8。Date对象内部只存储一个时间戳数值展示成什么时间取决于你调用的是「UTC 方法」还是「本地时间方法」。const date new Date(2024-06-01T14:30:00Z); // 读取 UTC 时间 console.log(date.getUTCHours()); // 14 // 读取本地时间假设你在东八区 console.log(date.getHours()); // 22同一个时间戳用不同的方法读取得到的小时数不同。这是时间函数中最容易混淆的点之一后面会详细展开。2. 环境准备与版本说明2.1 运行环境本文所有示例代码均使用 JavaScript可以在以下任意环境中运行浏览器控制台按 F12 打开开发者工具在 Console 中粘贴代码Node.js 环境建议 Node.js 14 以上版本在线代码编辑器如 CodePen、JSFiddle# 检查 Node.js 版本 node -v # 输出示例v18.20.02.2 关于时区设置的说明代码执行结果中的小时数会受操作系统时区影响。中国境内读者的本地时区一般是Asia/Shanghai即 UTC8。文中涉及本地时间与 UTC 时间比较的示例会额外说明时区影响。2.3 示例项目结构为了方便阅读本文的实战部分采用单文件示例不需要安装任何依赖time-function-demo/ ├── date-utils.js // 日期工具函数 ├── countdown.js // 倒计时示例 └── index.html // 简单的浏览器演示页面可选如果你使用 Node.js 运行示例直接在终端执行node date-utils.js3. Date 对象的核心 API 拆解3.1 创建 Date 对象的四种方式Date是 JavaScript 的内置构造函数创建它有四种常见方式。// 方式一不传参数得到当前时间 const now new Date(); console.log(now.toString()); // 输出Sat Jun 01 2024 22:30:00 GMT0800 (中国标准时间) // 方式二传毫秒时间戳 const fromTimestamp new Date(1717223400000); console.log(fromTimestamp.toISOString()); // 输出2024-06-01T14:30:00.000Z // 方式三传日期字符串 const fromString new Date(2024-06-01T14:30:00Z); console.log(fromString.toISOString()); // 输出2024-06-01T14:30:00.000Z // 方式四传多个数字参数年月日时分秒 const fromParams new Date(2024, 5, 1, 22, 30, 0); // 注意月份从 0 开始5 表示 6 月 console.log(fromParams.toString()); // 输出Sat Jun 01 2024 22:30:00 GMT0800 (中国标准时间)这里有几个关键细节必须说明第一字符串解析存在兼容性差异。new Date(2024-06-01 14:30:00)这种带空格的格式在旧版浏览器中解析结果可能不同推荐优先使用 ISO 8601 格式YYYY-MM-DDTHH:mm:ss.sssZ。第二多参数构造函数的月份是从 0 开始计数的。new Date(2024, 5, 1)表示的是 2024 年 6 月 1 日而不是 5 月 1 日。这是新手最容易踩的坑。第三多参数方式创建的时间是本地时间而字符串2024-06-01T14:30:00Z是UTC 时间两者含义不同。3.2 获取时间的 getter 方法创建了Date对象之后我们如何读取年、月、日、时、分、秒Date对象提供了一系列get方法每个方法都有对应的 UTC 版本本地时间方法UTC 时间方法返回值说明getFullYear()getUTCFullYear()四位年份getMonth()getUTCMonth()月份从 0 开始0 表示一月getDate()getUTCDate()几号从 1 开始getDay()getUTCDay()星期几从 0 开始0 表示周日getHours()getUTCHours()小时24 小时制getMinutes()getUTCMinutes()分钟getSeconds()getUTCSeconds()秒钟getMilliseconds()getUTCMilliseconds()毫秒看一个实际例子const date new Date(2024-06-01T14:30:00Z); // 本地时间假设东八区 console.log(date.getFullYear()); // 2024 console.log(date.getMonth()); // 56 月 console.log(date.getDate()); // 1 console.log(date.getDay()); // 6周六 console.log(date.getHours()); // 22 // UTC 时间 console.log(date.getUTCHours()); // 14这里最容易出错的就是getMonth()返回的月份比实际月份小 1。推荐在工具函数中写一个padZero补零函数然后统一对getMonth()加 1。3.3 设置时间的 setter 方法与 getter 对应Date对象也提供了set方法用于修改时间const date new Date(); // 设置为 2024 年 12 月 25 日 date.setFullYear(2024); date.setMonth(11); // 12 月 date.setDate(25); console.log(date.toDateString()); // 输出Wed Dec 25 2024需要注意的是setMonth()的月份参数同样是 0 开始的。此外当设置的日期超出范围时Date对象会自动进位const date new Date(2024, 0, 31); // 2024 年 1 月 31 日 date.setMonth(1); // 尝试设置为 2 月 31 日 console.log(date.toDateString()); // 输出Sat Mar 02 2024因为 2024 年 2 月没有 31 日JavaScript 自动将日期进位到了 3 月 2 日。这个特性一方面可以用来计算“某个月的下一个月的最后一天”另一方面也容易造成隐蔽的 bug需要特别留心。3.4 时间戳相关方法时间戳是时间函数中最核心的概念相关方法必须熟练掌握。// 获取当前时间戳毫秒 console.log(Date.now()); // 获取某个 Date 对象的时间戳 const date new Date(2024-06-01T14:30:00Z); console.log(date.getTime()); // 1717223400000 // 时间戳转 Date 对象 const timestamp 1717223400000; const date2 new Date(timestamp); console.log(date2.toISOString()); // 2024-06-01T14:30:00.000ZDate.now()是Date构造函数的静态方法可以直接调用。getTime()是实例方法返回该日期对象对应的时间戳。还有一个容易混淆的方法valueOf()它返回的值和getTime()相同const date new Date(2024-06-01T14:30:00Z); console.log(date.valueOf() date.getTime()); // true正因为Date对象重写了valueOf()所以两个时间可以直接比较大小const start new Date(2024-06-01T00:00:00Z); const end new Date(2024-06-02T00:00:00Z); console.log(end start); // true console.log(end - start); // 86400000毫秒数即一天3.5 时间格式化方法JavaScript 内置的格式化方法大概有四个各有特点const date new Date(2024-06-01T14:30:00Z); // 1. toString本地时间完整字符串 console.log(date.toString()); // Sat Jun 01 2024 22:30:00 GMT0800 (中国标准时间) // 2. toISOStringUTC 时间的 ISO 格式 console.log(date.toISOString()); // 2024-06-01T14:30:00.000Z // 3. toDateString只包含日期部分 console.log(date.toDateString()); // Sat Jun 01 2024 // 4. toLocaleString本地化的字符串 console.log(date.toLocaleString(zh-CN)); // 2024/6/1 22:30:00 console.log(date.toLocaleDateString(zh-CN)); // 2024/6/1其中toLocaleString()支持传入区域参数还可以传入配置项const date new Date(2024-06-01T14:30:00Z); const options { year: numeric, month: long, day: numeric, weekday: long, hour: 2-digit, minute: 2-digit }; console.log(date.toLocaleString(zh-CN, options)); // 输出2024年6月1日星期六 22:30注意toLocaleString()在不同运行环境下的输出格式可能有细微差别如果要求严格的输出格式还是需要自己封装格式化函数。4. 完整实战日期格式化工具函数4.1 需求分析在真实项目中我们经常需要把Date对象格式化成2024-06-01 22:30:00这种格式。虽然也可以用toLocaleString但输出结果可能不稳定。我们来手写一个formatDate函数支持自定义格式模板例如formatDate(date, YYYY-MM-DD HH:mm:ss)→2024-06-01 22:30:00formatDate(date, YYYY/MM/DD)→2024/06/01formatDate(date, MM-DD)→06-014.2 编写工具函数文件路径time-function-demo/date-utils.js/** * 将 Date 对象格式化为指定格式的字符串 * param {Date} date Date 对象 * param {string} template 模板字符串支持 YYYY、MM、DD、HH、mm、ss * returns {string} 格式化后的字符串 */ function formatDate(date, template YYYY-MM-DD HH:mm:ss) { if (!(date instanceof Date) || isNaN(date.getTime())) { throw new Error(formatDate 的第一个参数必须是合法的 Date 对象); } const padZero (num) String(num).padStart(2, 0); const year date.getFullYear(); const month padZero(date.getMonth() 1); const day padZero(date.getDate()); const hours padZero(date.getHours()); const minutes padZero(date.getMinutes()); const seconds padZero(date.getSeconds()); return template .replace(YYYY, year) .replace(MM, month) .replace(DD, day) .replace(HH, hours) .replace(mm, minutes) .replace(ss, seconds); } // 测试示例 const now new Date(); console.log(formatDate(now, YYYY-MM-DD HH:mm:ss)); // 输出示例2024-06-01 22:30:00 console.log(formatDate(now, YYYY年MM月DD日)); // 输出示例2024年06月01日 console.log(formatDate(now, HH:mm:ss)); // 输出示例22:30:004.3 函数设计要点解析这个函数虽然简单但有两个设计细节值得学习。第一个细节是参数校验。formatDate首先检查传入的参数是不是合法的Date对象。isNaN(date.getTime())用来排除无效日期例如new Date(invalid)创建的 Date 对象getTime()会返回NaN。const invalidDate new Date(invalid-date); console.log(isNaN(invalidDate.getTime())); // true第二个细节是模板替换的顺序。模板中使用YYYY、MM、DD、HH、mm、ss作为占位符替换时先替换长的占位符避免出现YYYY被YY部分匹配的问题。4.4 封装 UTC 格式化版本有些场景下我们需要把时间以 UTC 格式展示避免本地时区造成偏差。可以给工具函数增加一个参数function formatDate(date, template YYYY-MM-DD HH:mm:ss, useUTC false) { if (!(date instanceof Date) || isNaN(date.getTime())) { throw new Error(formatDate 的第一个参数必须是合法的 Date 对象); } const padZero (num) String(num).padStart(2, 0); const year useUTC ? date.getUTCFullYear() : date.getFullYear(); const month padZero((useUTC ? date.getUTCMonth() : date.getMonth()) 1); const day padZero(useUTC ? date.getUTCDate() : date.getDate()); const hours padZero(useUTC ? date.getUTCHours() : date.getHours()); const minutes padZero(useUTC ? date.getUTCMinutes() : date.getMinutes()); const seconds padZero(useUTC ? date.getUTCSeconds() : date.getSeconds()); return template .replace(YYYY, year) .replace(MM, month) .replace(DD, day) .replace(HH, hours) .replace(mm, minutes) .replace(ss, seconds); } const date new Date(2024-06-01T14:30:00Z); console.log(formatDate(date, YYYY-MM-DD HH:mm:ss, false)); // 东八区输出2024-06-01 22:30:00 console.log(formatDate(date, YYYY-MM-DD HH:mm:ss, true)); // UTC 输出2024-06-01 14:30:004.5 运行与验证在time-function-demo目录下执行node date-utils.js预期输出2024-06-01 22:30:00 2024年06月01日 22:30:00 2024-06-01 22:30:00 2024-06-01 14:30:00具体的小时数取决于你执行代码时的系统时区。如果在东八区本地时间会比 UTC 时间早 8 小时也就是数值上大 8。5. 完整实战倒计时功能实现5.1 需求分析倒计时是时间函数最常见的应用场景之一。例如电商平台秒杀活动倒计时短信验证码 60 秒重发倒计时考试剩余时间提示核心思路很简单用目标时间戳减去当前时间戳得到剩余的毫秒数再换算成天、时、分、秒。5.2 实现倒计时函数文件路径time-function-demo/countdown.js/** * 计算目标时间与当前时间之间的差值 * param {Date | string | number} target 目标时间 * returns {Object} 包含天、时、分、秒、毫秒的对象 */ function getCountdown(target) { const targetTime new Date(target).getTime(); const nowTime Date.now(); const diff Math.max(0, targetTime - nowTime); // 1 秒 1000 毫秒 // 1 分 60 秒 // 1 时 60 分 // 1 天 24 时 const day Math.floor(diff / (24 * 60 * 60 * 1000)); const hours Math.floor((diff / (60 * 60 * 1000)) % 24); const minutes Math.floor((diff / (60 * 1000)) % 60); const seconds Math.floor((diff / 1000) % 60); const milliseconds diff % 1000; return { day, hours, minutes, seconds, milliseconds }; } // 测试示例距离目标时间还有多少天 const target 2024-12-31T23:59:5908:00; const countdown getCountdown(target); console.log(countdown); // 输出示例 // { day: 198, hours: 21, minutes: 12, seconds: 34, milliseconds: 567 }5.3 格式化倒计时输出为了让输出更好看可以配合上一节的formatDate函数做一个格式化方法function formatCountdown(target) { const { day, hours, minutes, seconds } getCountdown(target); const padZero (num) String(num).padStart(2, 0); if (day 0) { return ${day}天${padZero(hours)}小时${padZero(minutes)}分${padZero(seconds)}秒; } return ${padZero(hours)}:${padZero(minutes)}:${padZero(seconds)}; } console.log(formatCountdown(2024-12-31T23:59:5908:00)); // 输出示例198天21小时12分34秒5.4 在浏览器中执行每秒刷新上面的函数只计算一次如果要实现每秒刷新的效果需要结合setInterval定时器// 在浏览器中运行 function startCountdown(target, onUpdate) { const timer setInterval(() { const result formatCountdown(target); // 回调函数将结果渲染到页面 onUpdate?.(result); // 倒计时结束清除定时器 const diff new Date(target).getTime() - Date.now(); if (diff 0) { clearInterval(timer); } }, 1000); // 返回清除函数方便外部停止 return timer; } // 使用示例 startCountdown(2024-12-31T23:59:5908:00, (text) { console.log(text); });这里需要注意setInterval的最小间隔不一定准确运行环境如果被切到后台浏览器可能会降低定时器频率。所以正确的做法是每次计算时重新获取当前时间戳而不是在每次回调里做简单的减 1 操作。上面的代码正是这样处理的每次通过Date.now()重新计算差值。5.5 时间差计算的常见误区在做时间差计算时最容易出现的错误是直接对年、月、日做“减法”。假设要计算两个日期之间相差多少天// 错误示例不能直接相减日期组件 const startDate new Date(2024, 5, 1); // 2024-06-01 const endDate new Date(2024, 5, 10); // 2024-06-10 // 这样得到的只是“小时间单位”的差值但月份不同时会失效 // 正确做法先转成时间戳再相减 const diffDays (endDate.getTime() - startDate.getTime()) / (24 * 60 * 60 * 1000); console.log(diffDays); // 9为什么不能直接写endDate.getDate() - startDate.getDate()因为如果跨月比如2024-05-28到2024-06-03直接减日期得到的是3 - 28 -25这显然是错误的。时间戳相减才是通用的做法。6. 常见问题与排查思路6.1 月份少一个月这是Date对象最经典的坑。问题现象常见原因解决思路getMonth()返回 5但实际是 6 月JavaScript 的月份从 0 开始获取时手动加 1new Date(2024, 5, 1)得到 6 月 1 日构造函数的月份参数从 0 开始传入月份时减 1setMonth(5)后日期变成 6 月set 方法与 get 方法一样0 开始先查阅文档确认参数含义排查方法const date new Date(2024, 5, 1); console.log(date.toString()); // Sat Jun 01 2024说明 5 表示 6 月6.2 无效日期返回 NaN当日期字符串无法解析时Date对象不会报错而是变成一个“无效日期”。对无效日期调用任何取值方法都会得到NaN。const invalid new Date(hello); console.log(invalid.toString()); // Invalid Date console.log(invalid.getTime()); // NaN当NaN参与运算时结果也是NaN这会沿着代码逻辑一路传播最终导致页面渲染出奇怪的NaN或Invalid Date。建议在接收外部日期数据时做一次合法性校验function isInvalidDate(date) { return !(date instanceof Date) || isNaN(date.getTime()); }6.3 时区导致格式化结果不一致问题现象常见原因解决思路同一个时间戳在本地显示 22:30在服务器显示 14:30本地方法读取的是本地时区使用getUTC*系列方法toISOString()与本地时间相差 8 小时ISO 格式固定展示 UTC 时间确认展示场景需要哪种时间从前端传入的2024-06-01被解析成 UTC 时间部分环境对纯日期字符串按 UTC 解析统一使用 ISO 完整格式并明确时区具体来说new Date(2024-06-01)在有些浏览器中被当作 UTC 时间在另一些环境中被当作本地时间兼容性不好。推荐统一写成new Date(2024-06-01T00:00:0008:00)明确指定时区偏移。6.4 定时器导致倒计时不准确问题现象常见原因解决思路倒计时每秒减 1但页面切后台再回来时间错乱setInterval在后台被节流每次都重新获取Date.now()多个定时器叠加倒计时加速未清理之前的定时器使用clearInterval清理服务器时间与本地时间不一致客户端系统时间被修改以服务器时间为基准计算偏移量更稳妥的倒计时方案是启动时从服务器获取一次标准时间计算本地时间与服务器时间的偏移量后续所有计算都基于“本地时间 偏移量”来推算。6.5 时间字符串解析兼容性不同 JavaScript 运行环境对日期字符串的解析支持不同尤其是旧版浏览器。推荐做法// 推荐使用 ISO 8601 格式 const date new Date(2024-06-01T14:30:0008:00); // 避免使用非标准格式 // const date new Date(2024/06/01 14:30:00);如果不确定字符串格式是否兼容可以先解析成时间戳function parseDateString(str) { const timestamp Date.parse(str); if (isNaN(timestamp)) { throw new Error(无法解析日期字符串: ${str}); } return new Date(timestamp); }Date.parse()是Date的静态方法返回的是毫秒时间戳解析失败时返回NaN。7. 最佳实践与工程建议7.1 统一使用时间戳进行传输和计算前后端接口传输时间时尽量使用时间戳或 ISO 8601 字符串不要依赖“2024-06-01 22:30:00”这种本地化格式。原因有两个时间戳包含完整的时区信息不会因为服务器在海外而出现偏差。时间戳做比较和运算最方便不需要解析字符串。// 接口返回的推荐格式 { createdAt: 2024-06-01T14:30:00.000Z }7.2 不直接操作 Date 对象的场景Date对象的 API 设计偏老很多操作写起来冗长且容易出错。如果你的项目已经有dayjs或date-fns这类库建议直接使用库提供的函数尤其是在处理时区、复杂日期计算时。// 使用 dayjs 的示例需要先安装依赖 // import dayjs from dayjs; // // const date dayjs(2024-06-01T14:30:00Z); // console.log(date.format(YYYY-MM-DD HH:mm:ss));但如果只是简单展示时间原生Date配合封装好的工具函数完全够用不必为了用库而用库。7.3 记录日志时明确时区在服务端记录日志时建议统一使用 UTC 时间并在日志格式中体现时区function formatLogTime(date new Date()) { return date.toISOString(); } console.log([${formatLogTime()}] 用户登录成功); // 输出示例[2024-06-01T14:30:00.000Z] 用户登录成功toISOString()输出的格式包含Z后缀明确表示这是 UTC 时间不会产生歧义。7.4 使用不可变思路处理时间Date对象的set方法会修改原对象在复杂逻辑中容易引发副作用。推荐的做法是每次修改都创建新的Date对象// 不推荐修改了原对象 const date new Date(); date.setHours(0, 0, 0, 0); // 推荐创建新对象 function startOfDay(date) { return new Date(date.getFullYear(), date.getMonth(), date.getDate()); } const originalDate new Date(); const dayStart startOfDay(originalDate); console.log(originalDate.getTime() ! dayStart.getTime()); // true7.5 性能方面的注意事项时间计算本身非常快一般不需要担心性能。但在以下场景中需要留意在循环中频繁创建Date对象并调用toISOString()如果数量达到十万级可以考虑复用对象。页面中有大量时间展示时不要每个组件独立调用Date.now()可以在应用启动时统一获取一次基准时间。网络传输中避免发送高精度时间字符串按需控制毫秒位数。7.6 单元测试建议时间函数比较适合做单元测试因为输入输出是确定的。写测试时注意覆盖以下边界情况// 测试用例设计提示 const testCases [ { name: 普通日期, input: new Date(2024, 5, 1, 12, 30, 0), expected: 2024-06-01 12:30:00 }, { name: 月份补零, input: new Date(2024, 0, 5, 8, 5, 5), expected: 2024-01-05 08:05:05 }, { name: 年份补零, input: new Date(999, 0, 1), expected: 0999-01-01 00:00:00 }, { name: 非法日期, input: new Date(invalid), expected: throw } ]; console.log(testCases);对工具函数formatDate来说重点要覆盖跨年、补零、闰年 2 月 29 日、无效日期等场景。7.7 时间性能优化清单如果你在项目中负责时间相关的公共模块可以按照下面的清单检查一遍所有时间字段的传输格式是否统一为时间戳或 ISO 8601展示层是否封装了统一的格式化工具避免到处写getMonth() 1倒计时、定时器等场景是否每隔一定时间重新校准当前时间服务端日志是否明确记录了时区是否覆盖了无效日期的处理逻辑关键日期计算是否有单元测试保障8. 总结与学习路线本文围绕 JavaScript 时间函数的核心内容进行了系统梳理从时间戳、UTC、本地时间等基础概念出发详细拆解了Date对象的创建、取值、设置、时间戳转换和格式化方法并通过日期格式化工具函数和倒计时两个完整案例演示了时间函数的实际应用。学完这篇文章你应该能够独立完成以下任务使用不同方式创建Date对象并理解各种方式之间的时区差异。熟练获取和设置年、月、日、时、分、秒避开getMonth()从 0 开始的问题。将Date对象与时间戳互相转换完成时间差计算。封装自己的时间格式化函数满足项目中自定义格式的需求。使用时间戳差值实现准确的倒计时功能。排查Invalid Date、时区偏差、月份错位等常见问题。下一步可以继续学习以下方向使用dayjs或date-fns简化日常时间处理。深入理解Intl.DateTimeFormat掌握更复杂的国际化时间展示。学习Temporal提案了解 JavaScript 时间处理的未来趋势。了解后端时间存储规范理解UTC、ISO 8601在跨端协作中的重要性。时间函数的内容并不复杂但它与每个项目都息息相关值得花时间彻底弄清楚。建议你打开浏览器控制台把本文中的示例代码逐一运行一遍再尝试封装一个自己的时间工具函数。只有亲手写过一遍才算是真正掌握了。