企业官网建设流程全解析

时间函数在不同编程语言里都是“看起来很简单，一用就出问题”的代表。尤其是前端开发，很多项目跑着跑着，突然某一天线上页面显示的日期全部差了 8 个小时，或者月份莫名其妙多了 1 个月，又或者同一个时间戳在 Windows 和 macOS 上格式化成完全不同的字符串。遇到这些问题时，很多人第一反应是“是不是我的代码写错了”，但查来查去，发现自己在调用 Date 对象的某个方法时，踩中了语言设计本身留下的坑。

这篇文章不打算只罗列 API 清单，而是想从一个更底层的角度看时间函数：时间戳、时区、格式化、解析、日期计算，这些问题背后的模型是什么，为什么 Date 对象会带来这么多困扰，以及当前前端生态里推荐怎么处理时间相关的需求。核心判断放在前面：大部分时间函数问题，根源不在于你不会用 API，而在于你没有建立“时间模型”的意识。如果你能把“时间点”和“时间的显示方式”分开来理解，绝大多数日期 bug 都会变得清晰可解。

读完这篇文章，你会得到一套可以直接用的时间处理方案，包括怎么安全地格式化日期、怎么处理时区、怎么计算日期差，以及项目里应该选择哪一类时间库。内容以 JavaScript / TypeScript 为例，但很多思路对 Java、Python 同样适用。

1. 为什么时间函数总是让人头疼

先看几个真实项目里非常常见的场景。

第一个场景：后端返回了一个时间字符串2024-06-15T12:00:00Z，前端拿到之后直接用new Date(str)解析，然后调用date.getHours()想取小时数。如果你的用户在 UTC+8 时区，这里拿到的不是 12，而是 20。很多新手看到这个结果会以为解析失败了，但实际上 Date 对象已经正确存储了时间点，只是getHours()返回的是本地时区的小时数。

第二个场景：用户选择了生日1995-08-23，前端把这份数据提交给后端保存。后端是 Java 服务，用LocalDate解析，存到数据库date字段。一切正常。但如果前端用new Date('1995-08-23')创建对象再传给后端，这个字符串会被当作 UTC 时间解析，在 UTC+8 地区等于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 UTC（Unix 纪元）开始经过的毫秒数（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.000Z"

2.2 UTC 与 GMT：让全世界有共同标准

UTC（协调世界时，Coordinated Universal Time）是全球统一的时间标准。它以原子钟为基础，与 GMT（格林尼治标准时间）在民用时间上基本一致，但技术定义不同。

所有国际化的系统，都倾向于在存储和传输时间时使用 UTC，因为这样可以避免时区歧义。一个时间字符串如果带上了Z后缀（比如2024-06-15T12:00:00Z），就表示它是 UTC 时间。Z代表“Zulu time”，即零时区。

2.3 本地时区：用户感知的时间

本地时区是指用户所在地区的时间偏移。比如北京是 UTC+8，东京是 UTC+9，纽约在夏令时期间是 UTC-4。

JavaScript 的 Date 对象提供了一套“本地时间”方法（getHours()、getMonth()）和一套“UTC 时间”方法（getUTCHours()、getUTCMonth()）。前者返回的是操作系统时区下的时间，后者返回的是 UTC 时间。

const date = new Date('2024-06-15T12:00:00Z'); // 本地时间（假设在 UTC+8 时区） 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 时间模型的核心结论

建立这个时间模型后，你会发现时间函数可以分成两类：

1. 从时间戳/Date 对象获取时间信息的函数（getTime()、getFullYear()、getUTCHours()等）。
2. 从时间信息构造时间戳/Date 对象的函数（new Date(year, month, day)、Date.UTC()、Date.parse()等）。

前者是“拆箱”，后者是“装箱”。拆箱和装箱之间，必须明确一个关键语义：是本地时间还是 UTC 时间。如果你在存储时用了 UTC，在读取时也统一用 UTC，就不会出错。如果你在构造时用了本地时间，在存储时却转成了 UTC，就可能出现时区偏移。

3. 时间戳与 Date 对象的底层细节

3.1 Date 对象的核心方法体系

JavaScript 的 Date 对象方法虽然多，但可以按用途归类。

需要特别提醒的是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()); // 15

3.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:00+08: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。如果你的服务器运行在 UTC+8 时区，然后把这个对象转成 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.000Z"（UTC+8 时区）

这就是为什么有些后端开发在读取前端传来的日期时，会多出 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:00+08: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:00+08: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()); // UTC+8 时区输出：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)); // 29（2024 年 2 月是闰年） console.log(getDaysInMonth(2024, 0)); // 31（2024 年 1 月）

这个技巧的核心就是new Date(year, month + 1, 0)，它返回的是“下个月的第 0 天”，即本月的最后一天，从而直接得到当月总天数。

6. 时区处理实战：跨时区项目怎么设计

如果你做的是纯国内项目，服务器和用户都在中国，时区问题可以很简单：统一使用 GMT+8 存储、展示，不做转换。但一旦你开始做国际化产品，或者使用海外云服务，时区问题就绕不开了。

6.1 后端存储的最佳实践

行业内的经典结论是：存储统一用 UTC，展示按用户本地时区转换。

• 数据库字段：使用timestamp with time zone类型（PostgreSQL）或 UTC 的datetime（MySQL 中建议使用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），而不是UTC+8这种偏移量。因为夏令时会导致偏移量在不同季节不同，IANA 时区名才能正确反映完整规则。

6.3 避免手写时区偏移逻辑

很多新手会尝试自己写“UTC+8”的处理逻辑，例如：

// 不推荐的写法 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.js

Day.js 是目前在国内社区最流行的库之一。它的 API 设计与 Moment.js 高度兼容，迁移成本低，但它的核心包只有约 2KB，通过插件支持更多功能。

npm install dayjs

import 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 dayjs

import 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:00

7.3 date-fns

date-fns 是一组纯函数工具库，它的设计哲学是“每个函数只做一件事”。如果你喜欢函数式编程风格，或者希望只打包用到的函数，date-fns 很合适。

npm install date-fns

import { 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 Luxon

Luxon 是 Moment.js 原作者团队推出的新库，底层使用原生Intl能力，对时区和间隔处理更专业。如果项目需要复杂的时间区间、闰秒等高级功能，Luxon 值得关注。

npm install luxon

import { 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 选型建议

一个务实的建议是：如果你的团队已经熟悉 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. 常见问题与排查方法

时间函数的报错通常不是直接抛出异常，而是返回错误值，因此排查时需要靠日志和断言定位。

这里还要特别提醒一点：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 都更有价值。