时间函数在不同编程语言里都是“看起来很简单一用就出问题”的代表。尤其是前端开发很多项目跑着跑着突然某一天线上页面显示的日期全部差了 8 个小时或者月份莫名其妙多了 1 个月又或者同一个时间戳在 Windows 和 macOS 上格式化成完全不同的字符串。遇到这些问题时很多人第一反应是“是不是我的代码写错了”但查来查去发现自己在调用 Date 对象的某个方法时踩中了语言设计本身留下的坑。这篇文章不打算只罗列 API 清单而是想从一个更底层的角度看时间函数时间戳、时区、格式化、解析、日期计算这些问题背后的模型是什么为什么 Date 对象会带来这么多困扰以及当前前端生态里推荐怎么处理时间相关的需求。核心判断放在前面大部分时间函数问题根源不在于你不会用 API而在于你没有建立“时间模型”的意识。如果你能把“时间点”和“时间的显示方式”分开来理解绝大多数日期 bug 都会变得清晰可解。读完这篇文章你会得到一套可以直接用的时间处理方案包括怎么安全地格式化日期、怎么处理时区、怎么计算日期差以及项目里应该选择哪一类时间库。内容以 JavaScript / TypeScript 为例但很多思路对 Java、Python 同样适用。1. 为什么时间函数总是让人头疼先看几个真实项目里非常常见的场景。第一个场景后端返回了一个时间字符串2024-06-15T12:00:00Z前端拿到之后直接用new Date(str)解析然后调用date.getHours()想取小时数。如果你的用户在 UTC8 时区这里拿到的不是 12而是 20。很多新手看到这个结果会以为解析失败了但实际上 Date 对象已经正确存储了时间点只是getHours()返回的是本地时区的小时数。第二个场景用户选择了生日1995-08-23前端把这份数据提交给后端保存。后端是 Java 服务用LocalDate解析存到数据库date字段。一切正常。但如果前端用new Date(1995-08-23)创建对象再传给后端这个字符串会被当作 UTC 时间解析在 UTC8 地区等于1995-08-23T08:00:00Z如果序列化时带上Z后缀后端收到的日期可能变成 8 月 23 日也可能变成 8 月 22 日具体取决于传输格式。第三个场景你要计算“三天后”的日期。很多人直接写date.setDate(date.getDate() 3)但如果你要跨月份比如 1 月 31 日加 3 天JS 会自动进位到 2 月 3 日表面看没问题。但如果要加的是“一个月”setMonth(date.getMonth() 1)则可能得到 3 月 2 日或 3 月 3 日因为 2 月没有 31 日。这个“进位”行为有时候符合预期有时候不符合。这些问题有一个共同点它们不是某个 API 的用法错误而是开发者没有理解 Date 对象内部到底存了什么以及各个方法在什么时区、什么语义下工作。所以这篇文章想先帮你建立时间处理的第一性原理时间是唯一的物理量但同一个时间点在不同时区、不同日历体系下有不同的表示方式。任何时间函数本质上都是在“绝对时间点”和“本地化字符串表示”之间做转换。2. 核心概念时间戳、UTC 与本地时区在深入代码之前必须先厘清几个基础概念。这些概念是所有时间函数的基石理解它们之后你才能解释清楚那些看似“玄学”的 bug。2.1 时间戳时间的绝对坐标时间戳Timestamp是计算机表示时间的标准方式。它通常指的是从 1970 年 1 月 1 日 00:00:00 UTCUnix 纪元开始经过的毫秒数JavaScript 中或秒数很多后端系统中。关键点在于时间戳没有时区概念。无论你在北京、纽约还是伦敦1718438400000这个数字都指向同一个瞬间。这是一种绝对的、与地域无关的时间坐标。在 JavaScript 中Date对象的内部就是存储一个时间戳数字。你可以通过date.getTime()获取它也可以通过Date.now()获取当前时间戳。// 获取当前时间戳毫秒 const timestamp Date.now(); console.log(timestamp); // 输出类似 1718438400000 // 通过时间戳创建 Date 对象 const date new Date(timestamp); console.log(date.toISOString()); // 2024-06-15T12:00:00.000Z2.2 UTC 与 GMT让全世界有共同标准UTC协调世界时Coordinated Universal Time是全球统一的时间标准。它以原子钟为基础与 GMT格林尼治标准时间在民用时间上基本一致但技术定义不同。所有国际化的系统都倾向于在存储和传输时间时使用 UTC因为这样可以避免时区歧义。一个时间字符串如果带上了Z后缀比如2024-06-15T12:00:00Z就表示它是 UTC 时间。Z代表“Zulu time”即零时区。2.3 本地时区用户感知的时间本地时区是指用户所在地区的时间偏移。比如北京是 UTC8东京是 UTC9纽约在夏令时期间是 UTC-4。JavaScript 的 Date 对象提供了一套“本地时间”方法getHours()、getMonth()和一套“UTC 时间”方法getUTCHours()、getUTCMonth()。前者返回的是操作系统时区下的时间后者返回的是 UTC 时间。const date new Date(2024-06-15T12:00:00Z); // 本地时间假设在 UTC8 时区 console.log(date.getHours()); // 20 console.log(date.getMonth() 1); // 6 // UTC 时间 console.log(date.getUTCHours()); // 12 console.log(date.getUTCMonth() 1); // 6这就是时区 bug 最常见的来源存储的是 UTC 时间但读取时用了本地方法。2.4 时间模型的核心结论建立这个时间模型后你会发现时间函数可以分成两类从时间戳/Date 对象获取时间信息的函数getTime()、getFullYear()、getUTCHours()等。从时间信息构造时间戳/Date 对象的函数new Date(year, month, day)、Date.UTC()、Date.parse()等。前者是“拆箱”后者是“装箱”。拆箱和装箱之间必须明确一个关键语义是本地时间还是 UTC 时间。如果你在存储时用了 UTC在读取时也统一用 UTC就不会出错。如果你在构造时用了本地时间在存储时却转成了 UTC就可能出现时区偏移。3. 时间戳与 Date 对象的底层细节3.1 Date 对象的核心方法体系JavaScript 的 Date 对象方法虽然多但可以按用途归类。方法分类本地时间方法UTC 时间方法无时区方法获取年份getFullYear()getUTCFullYear()-获取月份getMonth()getUTCMonth()-获取日期getDate()getUTCDate()-获取小时getHours()getUTCHours()-获取分钟getMinutes()getUTCMinutes()-获取秒getSeconds()getUTCSeconds()-获取毫秒getMilliseconds()getUTCMilliseconds()-获取时间戳--getTime()获取星期getDay()getUTCDay()-需要特别提醒的是getMonth()。它返回的值是 0-11其中 0 代表一月。这是新手最容易踩的坑new Date(2024, 0, 1)是 2024 年 1 月 1 日而不是 2024 年 0 月 1 日。每次拿月份做展示时都要记得加 1。const date new Date(2024, 5, 15, 10, 30, 0); console.log(date.getMonth()); // 5代表六月 console.log(date.getFullYear()); // 2024 console.log(date.getDate()); // 153.2 时间字符串解析的隐藏规则JavaScript 的Date.parse()和new Date(string)在解析字符串时行为并不完全一致而且不同浏览器对非标准格式的解析结果可能不同。标准格式推荐使用 ISO 8601即YYYY-MM-DDTHH:mm:ss.sssZ。这种格式在主流浏览器和 Node.js 中行为一致。// 推荐ISO 8601 格式 const date1 new Date(2024-06-15T12:00:00Z); const date2 new Date(2024-06-15T20:00:0008:00); // 两种写法都表示同一个时间点 console.log(date1.getTime() date2.getTime()); // true而不推荐的写法包括// 非标准格式不同环境解析结果可能不同 const date1 new Date(2024/06/15 12:00:00); const date2 new Date(06-15-2024); const date3 new Date(20240615);其中第一行在多数浏览器中会被当作本地时间解析但某些旧版本浏览器可能解析失败。第二行的年月日顺序在不同地区可能不同。第三行的纯数字字符串甚至可能被误解析为时间戳相关格式。因此在解析时间字符串时最稳妥的做法是显式指定格式或者使用第三方日期库来解析。3.3 构造函数的重载陷阱new Date()构造函数有几种重载行为差异很大new Date() // 当前时间 new Date(timestamp) // 从毫秒时间戳创建 new Date(dateString) // 从字符串解析 new Date(year, monthIndex, day, hours, minutes, seconds, ms) // 从年月日时分秒创建使用本地时区这里最容易出错的是最后一种当你用new Date(2024, 5, 15)创建对象时它使用的是本地时区而不是 UTC。如果你的服务器运行在 UTC8 时区然后把这个对象转成 ISO 字符串传给前端结果会变成2024-06-14T16:00:00.000Z日期少了 8 小时。如果你希望从年月日创建一个 UTC 时间应该用Date.UTC()// 创建 UTC 时间2024-06-15 00:00:00 UTC const utcDate new Date(Date.UTC(2024, 5, 15)); console.log(utcDate.toISOString()); // 2024-06-15T00:00:00.000Z // 创建本地时间2024-06-15 00:00:00 本地时区 const localDate new Date(2024, 5, 15); console.log(localDate.toISOString()); // 2024-06-14T16:00:00.000ZUTC8 时区这就是为什么有些后端开发在读取前端传来的日期时会多出 8 小时或者少 8 小时。本质上是前端构造 Date 对象时没有统一采用 UTC。4. 日期格式化与解析的正确姿势4.1 自定义格式化函数Date对象没有内置的format()方法toString()和toLocaleString()的格式因环境而异。因此在实际项目中你通常需要自己实现格式化或者使用第三方库。如果项目很小不想引入第三方库可以自己写一个简单的格式化函数。这里给出一个常用封装// 文件路径src/utils/dateFormat.js /** * 格式化日期 * param {Date} date - Date 对象 * param {string} fmt - 格式模板如 YYYY-MM-DD HH:mm:ss * returns {string} 格式化后的字符串 */ function formatDate(date, fmt YYYY-MM-DD HH:mm:ss) { const pad (n) (n 10 ? 0 n : n); return fmt .replace(YYYY, date.getFullYear()) .replace(MM, pad(date.getMonth() 1)) .replace(DD, pad(date.getDate())) .replace(HH, pad(date.getHours())) .replace(mm, pad(date.getMinutes())) .replace(ss, pad(date.getSeconds())); } // 使用示例 const now new Date(); console.log(formatDate(now)); // 输出类似2024-06-15 20:30:45 console.log(formatDate(now, YYYY年MM月DD日)); // 输出类似2024年06月15日这个函数的核心逻辑是用getFullYear()、getMonth()、getDate()等本地时间方法获取各个字段然后按模板拼接。它只能处理本地时间。如果你需要格式化 UTC 时间要把所有获取方法替换成对应的getUTC*版本。4.2 解析日期字符串解析日期字符串比格式化更危险因为解析失败不会抛异常而是返回Invalid Date。很多隐藏 bug 都是解析失败后代码继续执行直到最后的展示环节才发现数据异常。一个稳妥的自定义解析函数可以这样实现// 文件路径src/utils/dateParse.js /** * 解析 YYYY-MM-DD HH:mm:ss 格式的字符串返回 Date 对象本地时区 * param {string} str - 日期字符串 * returns {Date} 如果解析失败返回 null */ function parseDate(str) { if (!str) return null; const match str.match(/^(\d{4})-(\d{2})-(\d{2})(?:T|\s)(\d{2}):(\d{2}):(\d{2})$/); if (!match) return null; const [, y, m, d, hh, mm, ss] match; const date new Date(Number(y), Number(m) - 1, Number(d), Number(hh), Number(mm), Number(ss)); // 验证日期是否合法防止 month 为 13 之类的非法输入 if ( date.getFullYear() ! Number(y) || date.getMonth() ! Number(m) - 1 || date.getDate() ! Number(d) ) { return null; } return date; } // 使用示例 const date parseDate(2024-06-15 20:30:00); console.log(date); // 2024-06-15T20:30:0008:00取决于本地时区这段代码做了两件事先用正则提取年月日时分秒再通过new Date(year, month, day, ...)构造日期。构造之后用反向校验来判断输入是否合法避免new Date(2024, 13, 40)这种自动进位但明显非法的输入。4.3 Intl.DateTimeFormat 的使用如果你只是需要把日期显示成用户本地的习惯格式可以不自己拼字符串而是利用内置的Intl.DateTimeFormat。const date new Date(2024-06-15T20:30:0008:00); // 中文环境下的展示 const formatter1 new Intl.DateTimeFormat(zh-CN, { year: numeric, month: long, day: numeric }); console.log(formatter1.format(date)); // 输出2024年6月15日 // 英文环境下的展示 const formatter2 new Intl.DateTimeFormat(en-US, { year: numeric, month: long, day: numeric, hour: 2-digit, minute: 2-digit }); console.log(formatter2.format(date)); // 输出June 15, 2024 at 08:30 PM可能因环境略有差异这里要区分两个概念Intl.DateTimeFormat是展示层格式化它根据用户的语言环境和时区来显示时间适合你的应用已经存储了正确的时间点、只需要给用户展示的场景。而formatDate自写函数适合后端接口协议里固定格式的日期字符串比如日志文件名、定时任务触发时间。4.4 toISOString 与本地时间的关系date.toISOString()方法总是返回 UTC 时间的 ISO 8601 格式字符串带Z后缀。这是一个非常可靠的“传输格式”工具。const date new Date(2024, 5, 15, 20, 30, 0); // 本地时间 console.log(date.toISOString()); // UTC8 时区输出2024-06-15T12:30:00.000Z但由于它总是输出 UTC如果你用toISOString()把本地时间传给后端后端再按 UTC 解析时区就会丢失。因此在分布式系统中一个推荐的做法是前端统一把 Date 对象转成时间戳传给后端后端存时间戳或带时区的 ISO 字符串前端展示时再转换为本地时间。5. 日期计算与常见时间运算场景日期计算是时间函数最常见的应用场景之一。你需要计算 N 天后的日期、两个日期相差几天、某个月的最大天数、当月第一天是星期几等。这类需求看似基础但边界情况极多。5.1 毫秒级加减最简单、最安全的时间计算方式是把一切转换为毫秒时间戳再对时间戳做加减法。因为时间戳是绝对时间不涉及时区、进位的问题。// 计算 24 小时后的时间 const now new Date(); const tomorrow new Date(now.getTime() 24 * 60 * 60 * 1000); console.log(tomorrow); // 计算 7 天前的时间 const weekAgo new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000); console.log(weekAgo);这种方法的优点是语义明确24 * 60 * 60 * 1000就是一天整整 24 小时的毫秒数。它不涉及“跨月”“跨年”的进位规则因为时间戳永远是一条直线。但缺点是“加一天”和“加 24 小时”在夏令时切换的地区不完全等价。如果你只是给用户展示“明天的这个时间”使用时间戳加法在某些极端情况下可能会差 1 小时。不过在国内项目没有夏令时中这种差异基本不用考虑。5.2 基于日历单位的加减如果需要“下个月的 15 号”“明年 3 月 1 日”这类按日历单位运算就需要使用 Date 对象的setDate()、setMonth()等方法。特别注意月末进位问题。// 计算下个月的今天 function addMonth(date, count) { const d new Date(date); const day d.getDate(); d.setMonth(d.getMonth() count); // 如果月份改变后日期发生跃迁说明目标月份没有这个天数 if (d.getDate() ! day) { // 回退到目标月份的最后一天 d.setDate(0); } return d; } const date new Date(2024, 0, 31); // 2024-01-31 console.log(addMonth(date, 1).toDateString()); // 2024-02-29闰年如果 d.setDate(0) 没有被调用默认可能变成 2024-03-02这里的关键逻辑是d.setDate(0)在 JavaScript 中setDate(0)表示上个月的最后一天setDate(1)表示当月的第一天。利用这个特性可以安全地处理“1月31日加 1 个月”这类逻辑让结果落在“2月最后一天”而不是自动进位到 3 月。5.3 计算两个日期相差的天数两个日期之间的差推荐用时间戳计算然后换算为天数。function diffDays(date1, date2) { const msPerDay 24 * 60 * 60 * 1000; return Math.floor(Math.abs(date1.getTime() - date2.getTime()) / msPerDay); } const start new Date(2024-06-01T00:00:00Z); const end new Date(2024-06-15T00:00:00Z); console.log(diffDays(start, end)); // 14这种方法计算的是两个时间点之间的绝对毫秒差换算后的天数。注意它计算的是“绝对 24 小时单位”不是日历上的“自然日”。如果你要计算 “6月15日到6月17日” 的自然日差应该是 2 天但如果你把 6 月 15 日 18:00 和 6 月 17 日 08:00 做差按时间戳计算会得到 1 天多一些按 Math.floor 取整是 1 天。如果业务需要完全按自然日计算比如会员到期日更好的做法是比较年月日function diffCalendarDays(date1, date2) { const d1 new Date(date1.getFullYear(), date1.getMonth(), date1.getDate()); const d2 new Date(date2.getFullYear(), date2.getMonth(), date2.getDate()); return Math.round((d2 - d1) / (24 * 60 * 60 * 1000)); }5.4 获取某月的天数与特殊日期// 获取某年某月的天数 function getDaysInMonth(year, month) { // month 从 0 开始new Date(year, month 1, 0) 是下个月的第 0 天 return new Date(year, month 1, 0).getDate(); } console.log(getDaysInMonth(2024, 1)); // 292024 年 2 月是闰年 console.log(getDaysInMonth(2024, 0)); // 312024 年 1 月这个技巧的核心就是new Date(year, month 1, 0)它返回的是“下个月的第 0 天”即本月的最后一天从而直接得到当月总天数。6. 时区处理实战跨时区项目怎么设计如果你做的是纯国内项目服务器和用户都在中国时区问题可以很简单统一使用 GMT8 存储、展示不做转换。但一旦你开始做国际化产品或者使用海外云服务时区问题就绕不开了。6.1 后端存储的最佳实践行业内的经典结论是存储统一用 UTC展示按用户本地时区转换。数据库字段使用timestamp with time zone类型PostgreSQL或 UTC 的datetimeMySQL 中建议使用DATETIME配合应用层统一转 UTC或者TIMESTAMP由数据库处理具体看团队约定。API 传输统一使用带时区的 ISO 8601 字符串如2024-06-15T12:00:00Z或者直接用毫秒时间戳。后端日志建议打印 UTC 时间和本地时间两个值方便排查。6.2 前端的处理策略前端拿到后端返回的时间只有一种情况需要立刻转换为 Date 对象你需要在 JS 中做时间计算或格式化时。纯展示场景有时直接透传 ISO 字符串给 UI 组件也是可以的。如果你需要精确处理特定时区而不是让 JS 自动使用操作系统时区可以使用Intl.DateTimeFormat指定timeZone参数。// 指定时区转换不依赖服务器/浏览器本地时区 function formatInTimeZone(date, timeZone, locale zh-CN) { const formatter new Intl.DateTimeFormat(locale, { timeZone: timeZone, year: numeric, month: 2-digit, day: 2-digit, hour: 2-digit, minute: 2-digit, second: 2-digit, hour12: false }); return formatter.format(date); } const date new Date(2024-06-15T12:00:00Z); console.log(formatInTimeZone(date, Asia/Shanghai)); // 2024/06/15 20:00:00 console.log(formatInTimeZone(date, America/New_York)); // 2024/06/15 08:00:00夏令时这里要注意Intl.DateTimeFormat的timeZone参数必须是 IANA 时区名如Asia/Shanghai、America/New_York而不是UTC8这种偏移量。因为夏令时会导致偏移量在不同季节不同IANA 时区名才能正确反映完整规则。6.3 避免手写时区偏移逻辑很多新手会尝试自己写“UTC8”的处理逻辑例如// 不推荐的写法 const SHANGHAI_OFFSET 8 * 60 * 60 * 1000; const localDate new Date(utcDate.getTime() SHANGHAI_OFFSET);这种手写偏移的方式在纯“固定偏移时区”下看似可行但它完全忽略了夏令时变化在日期跨过夏令时边界时会得到错误结果。正确的做法是使用 IANA 时区规则比如Intl.DateTimeFormat或成熟的库如date-fns-tz、dayjs的插件。如果你不需要精确到秒级别的时区转换也可以考虑只在展示层用toLocaleString的timeZone选项。6.4 传输时区信息给前端如果后端返回的时间字符串没有带时区信息比如2024-06-15 12:00:00前端将无法确定它到底是 UTC 还是北京时间这类数据是“无时区”的。建议后端在接口文档中明确约定无时区字符串一律视为零时区 UTC或者一律视为用户本地时间的字符串。在实际项目中团队内部为日期字符串加上08:00后缀能大幅减少前端解析的歧义。7. 第三方时间库如何选Day.js、date-fns 与 Luxon原生 Date 的能力确实有限。真实项目中绝大多数团队都会引入一个时间库。这里重点对比几个常用库的选型思路。7.1 Moment.js 为何被官方宣布停止维护Moment.js 曾经是前端最主流的时间库但它的作者在 2020 年宣布项目进入维护模式不再增加新功能。原因是 Moment.js 的设计过于庞大国际化数据完整加载后体积很大而且它的对象是可变的容易在不知不觉中修改原有数据。官方推荐新项目使用其他现代库例如Day.js、date-fns或Luxon。7.2 Day.jsDay.js 是目前在国内社区最流行的库之一。它的 API 设计与 Moment.js 高度兼容迁移成本低但它的核心包只有约 2KB通过插件支持更多功能。npm install dayjsimport dayjs from dayjs; // 基础使用 const now dayjs(); console.log(now.format(YYYY-MM-DD HH:mm:ss)); // 2024-06-15 20:30:00 // 日期运算 console.log(dayjs(2024-06-15).add(1, day).format(YYYY-MM-DD)); // 2024-06-16 console.log(dayjs(2024-06-15).subtract(1, month).format(YYYY-MM-DD)); // 2024-05-15 // 比较 console.log(dayjs(2024-06-15).isAfter(2024-06-14)); // true // 获取时间戳 console.log(dayjs(2024-06-15).valueOf());Day.js 的插件机制也解决了时区问题但需要额外加载插件npm install dayjsimport dayjs from dayjs; import utc from dayjs/plugin/utc; import timezone from dayjs/plugin/timezone; dayjs.extend(utc); dayjs.extend(timezone); // 转换到指定时区 const date dayjs(2024-06-15T12:00:00Z); console.log(date.tz(Asia/Shanghai).format(YYYY-MM-DD HH:mm:ss)); // 2024-06-15 20:00:007.3 date-fnsdate-fns 是一组纯函数工具库它的设计哲学是“每个函数只做一件事”。如果你喜欢函数式编程风格或者希望只打包用到的函数date-fns 很合适。npm install date-fnsimport { format, addDays, differenceInDays, parseISO } from date-fns; // 格式化 console.log(format(new Date(), yyyy-MM-dd HH:mm:ss)); // 2024-06-15 20:30:00 // 日期运算 console.log(format(addDays(new Date(2024-06-15), 3), yyyy-MM-dd)); // 2024-06-18 // 日期差 console.log(differenceInDays( new Date(2024-06-18), new Date(2024-06-15) )); // 3 // 解析 ISO 字符串 console.log(parseISO(2024-06-15T12:00:00Z));date-fns 的体积优化更好只打包使用到的函数。但它的 API 不像 Day.js 那样链式命名风格也更接近 Lodash 风格。7.4 LuxonLuxon 是 Moment.js 原作者团队推出的新库底层使用原生Intl能力对时区和间隔处理更专业。如果项目需要复杂的时间区间、闰秒等高级功能Luxon 值得关注。npm install luxonimport { DateTime } from luxon; // 从 ISO 字符串解析 const dt DateTime.fromISO(2024-06-15T12:00:00Z); console.log(dt.toLocal().toFormat(yyyy-MM-dd HH:mm:ss)); // 指定时区转换 const dtShanghai dt.setZone(Asia/Shanghai); console.log(dtShanghai.toFormat(yyyy-MM-dd HH:mm:ss)); // 2024-06-15 20:00:00 // 计算时长 const end DateTime.fromISO(2024-06-20); console.log(end.diff(dt, days).toObject()); // { days: 4.5 }7.5 选型建议场景推荐理由国内项目需要低体积、低心智负担Day.jsMoment API 兼容上手快插件足够对 tree shaking 和函数式有要求date-fns体积可控、纯函数、按需导入复杂时区/区间计算LuxonIntl 底层支持 datetime 间隔和高级时区无第三方依赖偏好、小项目原生 Date 自封装工具函数零依赖维护成本低一个务实的建议是如果你的团队已经熟悉 Moment.js切到 Day.js 几乎是零成本如果你追求极致的构建体积和更现代的 API 风格date-fns 是更好的选择。8. 完整示例实现一个业务时间工具模块为了把前面的知识串起来这里提供一个实际项目中常见的工具模块。它包含格式化、解析、相对时间、自然日差、时区格式化等常用函数。// 文件路径src/utils/datetime.js import dayjs from dayjs; import utc from dayjs/plugin/utc; import timezone from dayjs/plugin/timezone; import relativeTime from dayjs/plugin/relativeTime; import dayjs/locale/zh-cn; dayjs.extend(utc); dayjs.extend(timezone); dayjs.extend(relativeTime); dayjs.locale(zh-cn); /** * 格式化本地时间 * param {Date|string|number} value - 日期值 * param {string} template - 模板 */ export function formatDate(value, template YYYY-MM-DD HH:mm:ss) { return dayjs(value).format(template); } /** * 格式化 UTC 时间 */ export function formatUTCDate(value, template YYYY-MM-DD HH:mm:ss) { return dayjs(value).utc().format(template); } /** * 格式化到指定时区 */ export function formatInZone(value, zone Asia/Shanghai, template YYYY-MM-DD HH:mm:ss) { return dayjs(value).tz(zone).format(template); } /** * 从字符串解析日期如果失败返回 null */ export function safeParse(value) { const d dayjs(value); return d.isValid() ? d : null; } /** * 自然日差比较两个日期的年月日 */ export function diffCalendarDays(date1, date2) { const d1 dayjs(date1).startOf(day); const d2 dayjs(date2).startOf(day); return d2.diff(d1, day); } /** * 相对时间3 小时前 / 2 天后 */ export function fromNow(value) { return dayjs(value).fromNow(); } /** * 获取某年某月的天数month 从 1 开始 */ export function getDaysInMonth(year, month) { return dayjs(new Date(year, month - 1, 1)).daysInMonth(); }使用示例const now new Date(); console.log(formatDate(now)); // 2024-06-15 20:30:00 console.log(formatUTCDate(now)); // 2024-06-15 12:30:00 console.log(formatInZone(now, Asia/Tokyo)); // 2024-06-15 21:30:00 console.log(safeParse(2024-13-45)); // null console.log(diffCalendarDays(2024-06-15, 2024-06-20)); // 5 console.log(fromNow(2024-06-15T10:00:00Z)); // 若干小时前 console.log(getDaysInMonth(2024, 2)); // 29这个工具模块的设计思路是基于 Day.js 封装统一团队的日期处理入口。对外暴露的方法都是纯函数不修改传入对象。如果后续需要替换底层库只需要改这个文件的内部实现不影响业务代码。9. 常见问题与排查方法时间函数的报错通常不是直接抛出异常而是返回错误值因此排查时需要靠日志和断言定位。问题现象可能原因排查方式解决方案日期少了 8 小时前端用本地时区构造 Date后端按 UTC 解析打印toISOString()查看 UTC 字符串统一传输时间戳或带时区的 ISO 字符串月份显示多了 1 个月getMonth()返回 0-11未加 1打印date.getMonth()调试手动加 1或使用库的格式化方法日期字符串解析失败new Date(2024-06-15 20:30:00)格式不支持使用isNaN(date.getTime())判断统一用YYYY-MM-DDTHH:mm:ss或第三方库不同浏览器格式化结果不一致使用了浏览器实现的非标准格式对比 Chrome 与 Safari 输出使用Intl.DateTimeFormat或 date-fns计算“下个月”时结果不对1 月 31 日加 1 个月自动进位为 3 月 2 日测试 1 月 31 日、3 月 31 日等边界日期使用setDate(0)回退到月末跨时区项目展示时间不正确未在Intl.DateTimeFormat中指定timeZone对比指定时区后的输出显式设置timeZone为 IANA 时区名时间戳被当作秒数据解析后端返回秒级时间戳前端用毫秒处理打印new Date(1718438400)看是否等于 1970 年 1 月后端统一秒/毫秒或前端做单位转换这里还要特别提醒一点Node.js 和浏览器对 Date 的解析存在细微差异尽量不要在生产环境直接依赖new Date(string)解析非标准字符串。如果必须要解析先加一层校验。10. 最佳实践与工程建议10.1 统一时间协议在前后端接口定义中建议明确时间的传输格式。一套比较常见的约定是时刻时间点使用 ISO 8601 带时区字符串例如2024-06-15T12:00:00Z。日期无时间使用YYYY-MM-DD不含T不含时区。时间戳仅在内部系统或定时任务场景使用避免与日期字符串混用。这个约定一旦确定前端和后端都需要遵守。它比任何代码技巧都重要。10.2 不要在业务代码里直接操作 Date 对象建议把时间操作全部收敛到工具模块里业务代码只调用语义明确的方法比如formatDate、parseDate、addMonth。这样做的好处是一旦发现时区 bug 或者边界问题只需要改一个文件而不用全局搜索setMonth。10.3 对用户输入做显式校验用户的浏览器可能输入2024-02-30、13月45日等非法日期。在构造 Date 对象后用“回读校验法”确认年月日没有发生自动进位function isValidDate(year, month, day) { const d new Date(year, month - 1, day); return d.getFullYear() year d.getMonth() month - 1 d.getDate() day; } console.log(isValidDate(2024, 2, 30)); // false console.log(isValidDate(2024, 2, 29)); // true闰年10.4 避免使用 Date 对象做唯一识别的标识某些场景下开发者会把时间戳当作唯一 ID 或缓存 key。高并发下Date.now()可能重复而且时间戳 ID 可按时间排序容易暴露业务量。如果你需要唯一标识用自增 ID 或 UUID。10.5 善用日志和哨兵在关键业务中建议对时间处理函数加上日志。比如用户注册时记录“前端收到时间、解析时间、存储时间”三个值。一旦出现时区问题就能快速定位是哪一层出的错。11. 展望Temporal API 是否会替代 Date在文章最后不得不提一下 JavaScript 的未来方向。TC39 的 Temporal API 提案目前处于较高成熟度阶段它试图解决 Date 对象的所有历史问题。Temporal 会区分PlainDateTime无时区的本地时间和ZonedDateTime带时区的时间并提供更加明确的日期计算 API比如add({ months: 1 })不会有自动进位问题而是会提供明确策略。// 未来 Temporal API 的示意语法可能调整不要直接用于生产 // const plainDate Temporal.PlainDate.from(2024-06-15); // const zoned Temporal.ZonedDateTime.from({ // timeZone: Asia/Shanghai, // year: 2024, // month: 6, // day: 15, // hour: 20 // });Temporal 的引入会从根本上改善 JS 的时间函数体验但目前它还没有被所有主流运行时默认支持生产环境使用需要 polyfill。因此在现在的项目中Day.js 或 date-fns 仍然是更稳的选择。但理解 Temporal 的设计思路能帮助你更好地建立时间模型因为它的 API 恰好把“时间点、时区、日历”这三个维度分得很清楚。当你下次再遇到时间函数相关的问题时可以按这个顺序自查第一这个时间值是绝对时间还是字符串第二字符串有没有带时区第三取时间和写时间用的方法是本地方法还是 UTC 方法第四日期计算是否涉及月末、年末的进位把这些问题想清楚大部分时间函数的问题都能定位到原因。这套方法论比记住任何 API 都更有价值。