时间函数是前端开发里最容易被低估的基础模块。倒计时、订单超时、日志时间、数据报表，几乎每个项目都逃不过时间处理。很多人能写出new Date()，但一遇到时区、格式化、跨月计算就开始反复试错。下面以 JavaScript 的Date对象为主线，把时间函数的创建、读取、计算、格式化、时区处理和常见坑串成一条可复现的排查链路。读完以后，你可以回到自己的项目里，用同样的顺序检查时间相关代码。
1. 时间函数的底层是时间戳，不是字符串
1.1 时间函数在做什么
时间函数不是“把当前时间变成字符串”这么简单。真正的时间函数要做两件事：
- 把一个具体的时刻保存下来。
- 把这个时刻按照某个时区翻译成年、月、日、时、分、秒等字段。
JavaScript 的Date对象底层保存的并不是字符串，而是从1970-01-01T00:00:00Z到某个时刻的毫秒数。这个整数也叫 Unix 毫秒时间戳。无论是new Date()、getTime()还是Date.now()，最终都在和这个整数打交道。
理解这一点很关键。你会发现，同一个Date对象，在不同时区的电脑上调用toString()会得到不同的年月日，但调用getTime()永远是同一个整数。因为“时刻”是固定的，只有“翻译成哪个时区”会变。
1.2 UTC、本地时间和时间戳的关系
先区分三个概念：
- UTC：世界协调时，可以理解成一个“全球统一的时间刻度”。
- 本地时间：当前运行环境所在时区下的时间。
- 时间戳：一个绝对整数，和时区无关。
举个例子，你在东八区执行下面这段代码：
const date = new Date(2024, 0, 1, 0, 0, 0); console.log(date.toString()); console.log(date.toISOString()); console.log(date.getTime());如果你所在的机器是Asia/Shanghai，那么输出可能是：
toString()：Mon Jan 01 2024 00:00:00 GMT+0800 (China Standard Time)toISOString()：2023-12-31T16:00:00.000ZgetTime()：1704067200000
这里toISOString()返回的是 UTC 时间，所以比本地时间少了 8 个小时。这个结果不是 bug，而是toString()和toISOString()分别用了两种时区去翻译同一个时间戳。
Date本身不包含时区信息，它只存一个毫秒数。所有getHours、getDate这类方法，都是根据当前机器的本地时区来翻译的。只要牵扯到“显示成几点几分”，就必须先明确时区。
1.3 先记住 Date 的关键 API
日常开发中，高频使用的 Date 方法可以先用一张表记住：
| 方法 | 作用 | 注意事项 |
|---|---|---|
Date.now() | 返回当前时间戳（毫秒） | 静态方法，不需要new |
new Date() | 创建当前时间的 Date 对象 | 无参构造 |
getTime() | 返回毫秒时间戳 | 适合比较和运算 |
getFullYear() | 返回 4 位年份 | 不要用getYear() |
getMonth() | 返回月份，0-11 | 0 表示 1 月 |
getDate() | 返回日期，1-31 | 注意是几号 |
getDay() | 返回星期，0-6 | 0 表示周日 |
getHours() | 返回小时，0-23 | 本地时区 |
getTimezoneOffset() | 返回本地与 UTC 的分钟差 | 东八区返回 -480 |
toISOString() | 返回 UTC 的 ISO 字符串 | 适合存储和传输 |
toLocaleString() | 返回本地化字符串 | 格式受运行环境影响 |
这些方法并不难，难的是组合使用。下一章用一个最小闭环把创建、读取、设置和格式化都跑一遍。
2. 创建、读取、设置和格式化，一个最小闭环先跑通
2.1 创建 Date 对象的四种方式
Date构造函数有四种常见用法：
// 1. 当前时间 const now = new Date(); // 2. 传入毫秒时间戳 const fromTimestamp = new Date(1735689600000); // 3. 传入 ISO 8601 字符串 const fromISO = new Date("2024-01-01T00:00:00Z"); // 4. 传入年月日时分秒 const fromParts = new Date(2024, 0, 1, 10, 30, 0, 0);这里最容易踩坑的是第四种。new Date(2024, 0, 1, 10, 30, 0, 0)的参数里，月份0表示 1 月。浏览器、Node.js 都会把这个组合解释成“本地时间”，而不是 UTC 时间。
如果确实想得到 UTC 时间，可以用Date.UTC：
const utcDate = new Date(Date.UTC(2024, 0, 1, 10, 30, 0, 0)); console.log(utcDate.toISOString()); // 2024-01-01T10:30:00.000Z实际项目中，服务端返回时间时建议直接返回 ISO 字符串或毫秒时间戳，前端不要自己拼“年月日时分秒”去构造Date，否则很容易把时区搞混。
2.2 读取年月日时分秒的推荐写法
读取字段时，getMonth()返回的是 0-11，所以展示月份要加 1：
function getLocalParts(date) { return { year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(), hour: date.getHours(), minute: date.getMinutes(), second: date.getSeconds(), weekDay: date.getDay() }; } console.log(getLocalParts(new Date("2024-01-01T00:00:00Z")));如果你的机器是东八区，new Date("2024-01-01T00:00:00Z")会显示成2024-01-01 08:00:00，所以上面输出的小时可能是 8。这不是错误，而是本地时区的正常翻译。
如果希望读取 UTC 对应的字段，把getFullYear换成getUTCFullYear，把getHours换成getUTCHours，其他字段同理。很多新人在排查时区问题时，会在getHours和getUTCHours之间反复切换，核心还是要先确定：你想展示给用户的是本地时间，还是 UTC 时间。
2.3 设置字段时要留意月份和溢出
setFullYear、setMonth、setDate、setHours都会修改原Date对象，并且返回修改后的时间戳。
常见错误是直接给 1 月 31 日加一个月：
const d = new Date(2024, 0, 31); d.setMonth(d.getMonth() + 1); console.log(d.toString());2024 年 2 月没有 31 日，JavaScript 会自动把日期溢出到 3 月 2 日（2024 年是闰年，2 月有 29 日）。这个行为在大多数情况下会带来隐藏 bug。如果你想要“下个月最后一天”或“月末”，可以换个思路：
function getMonthEndDate(year, month) { // month 从 1 到 12，new Date(year, month, 0) 表示下个月的第 0 天 return new Date(year, month, 0); } console.log(getMonthEndDate(2024, 2).getDate()); // 29，2024 年 2 月最后一天new Date(2024, 2, 0)里的month传 2，代表 3 月，但第 0 天会被解释为 3 月的前一天，也就是 2 月的最后一天。这种写法在日期库出现之前，是原生 JS 处理月末的常用技巧。
2.4 格式化输出尽量用 Intl，不要手拼字符串
手写补零格式化容易出问题，比如月份少加 1、小时没有补零：
function pad2(num) { return String(num).padStart(2, "0"); } function formatDateTime(date) { return ( date.getFullYear() + "-" + pad2(date.getMonth() + 1) + "-" + pad2(date.getDate()) + " " + pad2(date.getHours()) + ":" + pad2(date.getMinutes()) + ":" + pad2(date.getSeconds()) ); } console.log(formatDateTime(new Date()));这种写法能跑，但只在当前机器时区下正确。如果页面要展示固定的业务时区，推荐使用Intl.DateTimeFormat：
const formatter = new Intl.DateTimeFormat("zh-CN", { timeZone: "Asia/Shanghai", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23" }); console.log(formatter.format(new Date("2024-01-01T00:00:00Z")));Intl.DateTimeFormat的好处是格式稳定，可以在初始化时指定timeZone，并且同一个 formatter 对象可以重复使用，不需要在循环里反复 new。输出格式会受 locale 影响，但年月日时分秒的顺序和分隔符由内部规则决定，比手动拼字符串安全。
3. 时间计算与比较：毫秒是核心，但要避免直接改原对象
3.1 时间差计算的正确顺序
计算两个时间点之间的间隔，正确做法是先拿到毫秒时间戳，再做减法，最后换算成目标单位：
const start = new Date("2024-01-01T00:00:00Z"); const end = new Date("2024-01-02T00:00:00Z"); const diffMs = end.getTime() - start.getTime(); console.log(diffMs); // 86400000 console.log(diffMs / 1000 / 60 / 60); // 24 小时不要用end - start直接相减。虽然减法运算会隐式调用valueOf()得到毫秒数，但显式用getTime()更清晰，也能避免其他类型转换带来的意外。
如果要做日期的加减，比如加 7 天，可以先复制原对象，再用setDate：
function addDays(date, days) { const copy = new Date(date.getTime()); copy.setDate(copy.getDate() + days); return copy; } const d = new Date("2024-01-28T00:00:00Z"); console.log(addDays(d, 2).toISOString()); // 2024-01-30T00:00:00.000Z跨年、跨月时，setDate会自动处理溢出。比如 1 月 31 日加 1 天会变成 2 月 1 日。但要注意：这个操作修改的是复制出来的对象，不会污染原对象。
3.2 日期比较不要用 ==
两个Date对象不能直接用==判断是否相等，因为==比较的是对象引用，不是时间戳：
const a = new Date("2024-01-01T00:00:00Z"); const b = new Date("2024-01-01T00:00:00Z"); console.log(a == b); // false，两个不同对象 console.log(a.getTime() === b.getTime()); // true console.log(+a === +b); // true，一元加号也会转成时间戳比较大小可以用<、>，它们会先转成数值。但为了可读性和避免歧义，推荐统一用getTime()或时间戳变量比较。
3.3 加天、加月时先复制对象
在实际业务中，最常见的隐性 bug 是多个变量引用同一个Date对象，某个方法内部修改了它，导致外部数据也被改变：
const planStart = new Date("2024-03-01T00:00:00Z"); const planEnd = planStart; // 引用同一个对象 planEnd.setDate(planEnd.getDate() + 7); console.log(planStart.toISOString()); // 变到了 2024-03-08T00:00:00.000ZplanEnd 只是 planStart 的引用，改 planEnd 等于改 planStart。为了避免这个问题，任何“基于一个日期生成另一个日期”的逻辑，都应该先复制：
function copyDate(date) { return new Date(date.getTime()); }3.4 用 setFullYear(2024, 2, 0) 这类技巧取月底
除了上一章的月末写法，还可以用setDate(0)获取上一个月的最后一天，比如获取当前日期所在月份的最后一天：
const today = new Date(); const lastDayOfThisMonth = new Date(today.getFullYear(), today.getMonth() + 1, 0); console.log(lastDayOfThisMonth.toString());这里today.getMonth() + 1代表下一个月，第 0 天就是当月的最后一天。这个思路在生成月报、账单周期时非常常用。
4. 时区问题不靠猜，按这条链路排查
4.1 后端返回 UTC 时间，前端显示差 8 小时不是 bug
一个典型的时区问题是这样的：
后端返回: "2024-01-01T00:00:00Z" 前端渲染: 2024-01-01 08:00:00很多人的第一反应是要减掉 8 小时。实际上，"2024-01-01T00:00:00Z"表示 UTC 0 点，在前端东八区运行时，浏览器会自然把它显示成早上 8 点。这是符合预期的本地时间翻译。
真正需要判断的是产品诉求：
- 如果页面要展示“用户本地的时刻”，那么当前逻辑是对的。
- 如果页面要固定展示“北京时间”，则应该用
Intl.DateTimeFormat搭配timeZone: "Asia/Shanghai"。 - 如果页面要展示“和 UTC 一致的原始值”，则直接显示
toISOString()或后端原字符串。
排查时不要靠肉眼猜，先打印关键信息：
const raw = "2024-01-01T00:00:00Z"; const dt = new Date(raw); console.log(dt.toISOString()); // UTC 时间 console.log(dt.getTimezoneOffset()); // 当前环境时区偏移，东八区为 -480 console.log(dt.toString()); // 本地完整字符串4.2 toISOString、toLocaleString 和 getTimezoneOffset 的分工
这三个方法经常被混用，实际分工完全不同。
| 方法 | 时区 | 典型用途 |
|---|---|---|
toISOString() | 固定 UTC | 存储、传输、日志 |
toLocaleString() | 当前本地时区 + locale | 人肉查看、简单调试 |
getTimezoneOffset() | 当前本地时区偏移 | 判断运行环境时区，不是某一个 Date 的时区 |
getTimezoneOffset()返回的是“本地时间相比 UTC 相差多少分钟”，注意正负号是反的。东八区返回-480，因为本地时间比 UTC 早 480 分钟。它只能告诉你运行环境在哪一个时区，不能用来给某个日期设置时区。
如果需要把某个 UTC 时间转换成固定业务时区，不要这样写：
const bad = new Date(dt.getTime() + 8 * 3600 * 1000);这会把“时刻”本身改掉，只是为了让getHours()输出 8 点。如果后续再调用toISOString()或传给后端，就会出现二次偏移。正确做法是展示层指定timeZone：
const shanghaiFormatter = new Intl.DateTimeFormat("zh-CN", { timeZone: "Asia/Shanghai", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23" }); console.log(shanghaiFormatter.format(dt));4.3 只传日期字符串和传完整 ISO 字符串，解析规则不一样
这是 JavaScript 时间解析里很隐蔽的一个差异：
console.log(new Date("2024-01-01").toISOString()); console.log(new Date("2024-01-01T00:00:00").toISOString());在规范定义中，"2024-01-01"这种仅日期形式会被当成 UTC 时间解析，输出2024-01-01T00:00:00.000Z。而"2024-01-01T00:00:00"这种日期加时间但没有时区后缀的形式，会被当成本地时间解析。在东八区环境下，第二行输出的是2023-12-31T16:00:00.000Z。
这个差异很容易让前后端对不上。前端收到后端字符串时，要确认字符串是否带时区偏移：
- 带
Z：UTC 时间，可直接new Date(...)。 - 带
+08:00：明确的东八区时间，new Date(...)能正确解析。 - 只有日期和时间，没有偏移：规范会按本地时间处理，不适合跨时区系统。
所以，服务端接口字段最好统一返回带时区的 ISO 字符串，比如"2024-01-01T00:00:00.000Z"或"2024-01-01T08:00:00+08:00"。如果因为历史原因返回了"2024-01-01 00:00:00"，前端解析前最好先补充明确时区，而不是让浏览器按照本机时区猜。
5. 时间函数最常见的五个坑和排查清单
5.1 月份从 0 开始
几乎所有新手都会踩这个坑：
const d = new Date(2024, 11, 1); console.log(d.getMonth()); // 11getMonth()返回 0-11，想显示 12 月必须getMonth() + 1。年份、日期没有这个问题，只有月份特殊。建议封装一个getMonthZh之类的工具函数，统一处理加 1。
5.2 new Date(null) 等于 1970，new Date(undefined) 是 Invalid Date
这种问题通常来自接口返回了空值，前端没有判空就传给new Date()：
console.log(new Date(null).toISOString()); // 1970-01-01T00:00:00.000Z console.log(new Date(undefined).toString()); // Invalid Datenull会被强制转成0，所以得到 1970 年，看起来“能正常显示”，但实际是错误数据。undefined则直接变成 Invalid Date。在从接口拿时间字段时，必须先判空。
5.3 非标准字符串在不同引擎下表现不一致
new Date("2024/01/01 10:00:00")这类非 ISO 字符串在某些浏览器和 Node.js 版本下可以解析，但它依赖实现，不保证所有环境一致。生产环境不要依赖这种写法。
如果必须解析，稳妥的做法是：
- 要求后端返回时间戳或 ISO 字符串。
- 前端使用正则拆分字符串，然后使用
new Date(year, month, day, ...)或Date.UTC。 - 或者使用日期工具库解析。
5.4 直接修改原对象会污染业务状态
很多接口会返回一个时间字段，前端需要基于它生成开始时间和结束时间。如果直接修改原对象，后面的逻辑拿到的是被改过的值。
推荐做法是：任何“时间计算”都返回新对象，并且用函数名表明这一点，比如addDays、addMonths、getStartOfDay。团队内部可以约定，Date对象默认不可变，只有通过专门的工具函数或显式赋值才允许修改。
5.5 时间问题排查清单
拿到一个时间显示不对的问题，按下列顺序排查：
| 排查步骤 | 操作 | 判断标准 |
|---|---|---|
| 1. 确认原始值 | 打印接口返回的字段，看是否带时区 | 确认是 UTC、本地时间还是时间戳 |
| 2. 确认解析对象 | 打印new Date(raw).toISOString() | 看 UTC 时刻是否和预期一致 |
| 3. 确认运行环境 | 打印new Date().getTimezoneOffset() | 确认当前浏览器或 Node 的时区 |
| 4. 确认展示时区 | 打印toLocaleString()或Intl.DateTimeFormat结果 | 看显示结果属于哪一时区 |
| 5. 确认是否做了二次偏移 | 搜索代码里有没有手动加减时间戳 | 避免getTime() + 8 * 3600 * 1000这类写法 |
| 6. 确认格式化方法 | 检查是否用getMonth()且没有加 1 | 防止月份少 1 个月 |
这套顺序基本能解决 90% 的前端时间显示问题。
6. 时间函数的最佳实践和下一步扩展方向
6.1 在不同环境下的使用策略
学习环境里，可以直接用new Date()和toLocaleString()快速验证，不需要引入额外依赖。但到了生产环境，时间处理要遵循更严格的原则：
- 存储层：统一使用 UTC 时间或毫秒时间戳，避免数据库中存“本地时间字符串”。
- 接口层：统一返回带时区的 ISO 8601 字符串，例如
"2024-01-01T00:00:00.000Z"。 - 展示层：使用
Intl.DateTimeFormat指定用户或业务需要的时区。 - 计算层：用时间戳做运算，减少对
setHours、setMonth等修改式 API 的依赖。
生产环境还需要考虑日志。时间相关 bug 往往依赖输入数据，日志里最好同时记录原始字符串、toISOString()结果和最终格式化结果。这样排查时可以直接对比。
6.2 选原生还是日期库
原生Date能覆盖基础需求，但在复杂场景下不够直观，比如时间差、时区转换、日期时间戳计算。常见的日期库有：
| 方案 | 适用场景 | 注意 |
|---|---|---|
| 原生 Date | 简单格式化、基本时间戳计算 | 注意月份、时区、解析差异 |
| dayjs | 轻量项目、常用 API 封装 | API 简单，体积小 |
| date-fns | 函数式风格、按需引入 | 不可变设计，tree-shaking 友好 |
| Luxon | 复杂时区、业务时区转换 | DateTime 模型更接近业务 |
| Moment.js | 老项目迁移过渡 | 新项目一般不建议引入 |
如果只是几个页面显示时间，原生Intl.DateTimeFormat足够。如果项目里有大量时间区间、时区转换和周期性任务，用 dayjs 或 date-fns 能减少重复代码。真正遇到极端时区需求，再考虑 Luxon。
6.3 从 Date 继续深入的学习路线
时间函数是一个入口，深入下去可以分三条线继续学：
- JavaScript 语言线：学习
Intl.DateTimeFormat的完整参数，理解TemporalAPI 的提案方向。 - 服务端线：对比 Java 的
java.time、Go 的time包、Python 的datetime处理时区的方式。 - 数据库线：理解
TIMESTAMP WITH TIME ZONE、DATETIME、CURRENT_TIMESTAMP等字段语义。
时间处理本质是“全球统一的时刻”和“各种时区下的展示”之间的转换。先把Date的时间戳模型搞懂，再去看更高级的日期库和数据库时间类型，你会明显感觉那些设计都是在补Date的不足。回到项目里，可以从一个最简单的后台时间字段开始，走一遍“接口原始值、Date 解析、格式化展示、跨时区验证”的完整链路，这一步走通，时间函数的基本功也就稳了。
