系统讲解JavaScript Date对象的5种实例化方式、字符串解析时区差异、常用读取/修改/格式化方法速查,以及日期加减与避坑实践。
JavaScript Date对象常用方法速查与实例化详解
时间:2026-11-22
浏览:181
文章目录
写前端或 Node.js 代码时,很多人第一次踩 Date 的坑,往往是因为传入 new Date('2026-05-12') 后,在东八区环境里取出的小时数变成了 8;紧接着又会发现 getMonth() 对 5 月返回了 4。其实只要搞清楚 Date 内部只存一个 UTC 毫秒时间戳,并分清五种实例化方式和四类方法的作用边界,这些问题都能一次性理顺。本文会先讲透 Date 的内部模型与实例化细节,再提供按用途归类的常用方法速查表和常见操作写法。
一、理解 Date 的底层模型:一个时间戳与两套视角
在 JavaScript 中,无论通过哪种方式创建 Date 实例,对象内部保存的既不是“年月日字符串”,也不是时区信息,而仅仅是一个以 UTC 1970 年 1 月 1 日 00:00:00.000 为起点的毫秒整数(有效范围是起点前后各 8.64e15 毫秒,约正负 27 万年)。
之所以同一个 Date 对象在不同方法下表现出不同的时间,是因为它提供了两套读取与修改视角:
- 本地时间视角(默认):如
getHours()、toString()、toLocaleString(),会读取运行环境当前系统的时区偏移,把内部 UTC 时间戳换算成本地时间。 - UTC 视角:如
getUTCHours()、toISOString(),直接按零时区(UTC)拆解,不受设备所在时区影响。
二、Date 实例化的五种方式与解析细节
创建 Date 对象必须使用 new Date(...)。如果不写 new 直接调用 Date(),无论传什么参数,都会忽略参数并返回一个代表当前时间的字符串,而不是 Date 实例,因此无法调用 getFullYear() 等实例方法。
1. 无参数:获取当前时刻
new Date() 会根据当前系统时钟创建一个代表此时此刻的实例。
const now = new Date();
console.log(now instanceof Date); // 示例判断: true
console.log(typeof Date()); // 示例判断: "string"(未加 new)
2. 传入数字:毫秒时间戳
new Date(timestamp) 接收一个数字作为毫秒时间戳。后端接口(尤其是 Python、PHP、Go 或 MySQL Unix 时间戳)常返回 10 位的秒级时间戳,而 JavaScript 需要 13 位的毫秒级时间戳。直接把 10 位数传给 new Date() 会得到 1970 年 1 月的某一天,务必先乘以 1000。
const fromMs = new Date(1778544000000); // 2026-05-12T00:00:00.000Z
const fromSec = new Date(1778544000 * 1000); // 秒级时间戳先乘以 1000
3. 传入字符串:ISO 8601 与时区陷阱
这是最容易产生 8 小时偏差的实例化方式。按照 ECMAScript 规范,new Date(dateString)(内部规则与 Date.parse() 一致)对 ISO 8601 格式字符串的处理有明确区分:
- 纯日期字符串(不含时间):如
'2026-05-12'、'2026-05',规范强制按 UTC 零点解析。在东八区调用getHours()会得到8;如果写成'2026-05-12'想表示本地零点,结果就会偏移。 - 带时间但无时区后缀:如
'2026-05-12T00:00:00',按 本地时区解析。 - 带时区后缀:末尾有
Z(UTC)或+08:00等偏移量,如'2026-05-12T00:00:00+08:00',严格按指定时区解析,跨设备行为最稳定。
'2026-5-12'(未补零)、'05-12-2026' 或 '2026-05-12 08:30:00'(空格分隔而非 T)。不同浏览器和 JS 引擎对非标准格式的解析行为不统一,例如 Safari 早期版本会直接将空格分隔或横杠未补零的日期解析为 Invalid Date。如果日期来自用户输入,建议拆分出年月日数字或先标准化为带时区的 ISO 格式。
4. 传入数值分量:精准构造本地时间
new Date(year, monthIndex, day, hours, minutes, seconds, ms) 至少需要传入年份和月份两个参数,其余参数可选(day 默认为 1,时分秒毫秒默认为 0),全部按本地时区构造。
这种写法有三个细节需要记住:
- 月份从 0 开始:
0代表 1 月,11代表 12 月。传入 5 月必须写4。 - 溢出自动进位或借位:如果传入
day = 0,会自动退回到上个月最后一天;传入day = 32会顺延到下个月。利用new Date(2026, 2, 0)就能直接拿到 2026 年 2 月的最后一天(28 号)。 - 两位数年份映射:如果
year在0到99之间,会被自动加上1900,例如new Date(26, 4, 12)表示 1926 年而非 2026 年。若要构造公元 0~99 年,需先创建实例再调用setFullYear()。
如果希望用数值分量构造 UTC 时间而非本地时间,可以配合静态方法 Date.UTC():new Date(Date.UTC(2026, 4, 12, 0, 0, 0))。
5. 传入已有 Date 实例:安全克隆
new Date(existingDate) 会读取原实例的时间戳并生成一个全新对象。由于后续要介绍的 set* 方法会原地修改原对象,做日期计算前先用这种方式克隆一份,可以避免意外改坏原始数据。
实例化后如何验证有效性
当传入无法解析的字符串(如 new Date('abc'))或超出范围的数值时,new Date() 不会抛出异常,而是返回一个特殊的 Invalid Date 对象——它依然属于 Date 类型,但内部时间戳是 NaN。判断一个日期对象是否有效,应使用 Number.isNaN(d.getTime())(返回 true 表示无效)。
三、Date 常用方法速查表
把 Date 的方法按“静态工具、读取分量、修改分量、格式化输出”四组来记,实际写代码时查起来最快。
1. 静态方法(直接通过 Date 调用)
| 方法 | 作用与返回值 | 常见用途与说明 |
|---|---|---|
Date.now() |
返回当前时间的毫秒时间戳(Number) | 计算耗时、生成时间戳参数;比 new Date().getTime() 省去创建对象的开销 |
Date.parse(str) |
解析日期字符串,返回毫秒时间戳;失败返回 NaN |
解析规则与 new Date(str) 完全相同,纯校验或只取时间戳时可用 |
Date.UTC(y, m, ...) |
按 UTC 时区把数值分量转成毫秒时间戳 | m 同样从 0 开始;常配合 new Date(Date.UTC(...)) 使用 |
2. 读取时间分量(Getter)
以下列出最常用的本地时间读取方法。若需要读取零时区数值,把 get 换成 getUTC 即可(例如 getUTCFullYear()、getUTCHours())。
| 方法 | 返回值范围 / 含义 | 易错点提醒 |
|---|---|---|
getFullYear() |
4 位完整年份(如 2026) |
不要使用已废弃的 getYear()(2026 年会返回 126) |
getMonth() |
0 ~ 11(0 代表 1 月) |
展示给用户时必须 + 1 |
getDate() |
1 ~ 31(当月第几天) |
它才是“几号”,不要和 getDay() 混淆 |
getDay() |
0 ~ 6(0 代表周日) |
表示“星期几”,周一到周六分别是 1 ~ 6 |
getHours() / getMinutes() / getSeconds() |
时 0~23、分 0~59、秒 0~59 |
均为单个整数,不足两位不会自动补 0 |
getMilliseconds() |
0 ~ 999 |
常用于高精度日志或耗时统计 |
getTime() / valueOf() |
毫秒时间戳;无效日期返回 NaN |
两个 Date 比较早晚时可直接用 a.getTime() < b.getTime(),也支持直接 a - b 相减 |
getTimezoneOffset() |
UTC 与本地时间的分钟差(UTC - 本地) |
正负号容易看反:东八区(UTC+8)返回 -480,而不是 480 |
3. 修改时间分量(Setter)
set* 系列方法会直接修改当前 Date 实例的内部时间戳,并返回修改后的新毫秒时间戳,而不是返回一个新的 Date 对象。
| 方法 | 可传参数 | 核心行为 |
|---|---|---|
setFullYear(y [, m, d]) |
年份,可选月、日 | 可一次设置年月日;对应 UTC 版本为 setUTCFullYear() |
setMonth(m [, d]) |
月份(0~11),可选日 | 若原日期为 31 号而目标月不足 31 天,会自动顺延到下个月初 |
setDate(d) |
当月第几天 | 最稳妥的“加减天数”手段:d.setDate(d.getDate() + 7) 会自动跨月跨年 |
setHours(h [, m, s, ms]) |
小时,可选分、秒、毫秒 | 常用于把某天重置到零点:d.setHours(0, 0, 0, 0) |
setMinutes() / setSeconds() / setMilliseconds() |
分/秒/毫秒及更小单位 | 同样支持超出范围自动进位(如 setSeconds(70) 会让分钟加 1) |
setTime(ms) |
毫秒时间戳 | 直接整体替换实例时间,常用于复用同一个 Date 对象 |
4. 格式化与字符串转换方法
| 方法 | 输出格式示例(基于东八区示例时间) | 适用场景 |
|---|---|---|
toISOString() |
"2026-05-12T00:30:00.000Z" |
前后端接口传参、日志存储;永远输出 UTC 时间 |
toJSON() |
同 toISOString();无效日期返回 null |
JSON.stringify() 自动调用的方法 |
toLocaleString(locale, opts) |
"2026/5/12 08:30:00"(传 'zh-CN') |
按指定语言与格式展示给用户,支持自定义 timeZone |
toLocaleDateString() / toLocaleTimeString() |
"2026/5/12" / "08:30:00" |
仅展示本地日期部分或时间部分 |
toString() |
"Tue May 12 2026 08:30:00 GMT+0800 (...)" |
控制台调试,格式由语言环境决定,不建议用于接口或正则解析 |
toDateString() / toTimeString() |
"Tue May 12 2026" / "08:30:00 GMT+0800 (...)" |
英文可读调试文本 |
四、三个常见实战操作写法与验证
掌握上面方法后,日常开发最常遇到的是格式化补零、安全日期加减以及时区展示。下面直接在浏览器控制台或 Node.js 环境中可运行的示例代码,均避开了前面提到的常见陷阱。
操作 1:格式化为本地 YYYY-MM-DD HH:mm:ss
很多新手会直接写 d.toISOString().slice(0, 19).replace('T', ' '),但 toISOString() 输出的是 UTC 时间,在东八区会比本地时间少 8 小时。稳妥的做法是用本地 Getter 配合 String.prototype.padStart(2, '0') 补零:
function formatLocalDateTime(date) {
if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
throw new TypeError('请传入有效的 Date 实例');
}
const pad = (n) => String(n).padStart(2, '0');
const y = date.getFullYear();
const m = pad(date.getMonth() + 1);
const d = pad(date.getDate());
const hh = pad(date.getHours());
const mm = pad(date.getMinutes());
const ss = pad(date.getSeconds());
return `${y}-${m}-${d} ${hh}:${mm}:${ss}`;
}
const sample = new Date(2026, 4, 12, 8, 5, 3);
console.log(formatLocalDateTime(sample));
2026-05-12 08:05:03
操作 2:安全克隆后计算“N 天后”与“月份加减”
加减天数时,先用 new Date(source) 克隆,再调用 setDate(),不会改动原始对象;如果按月加减且希望保留月末对齐(比如 1 月 31 日加 1 个月变成 2 月 28 日而不是 3 月 3 日),需要在修改月份后比对目标日并钳位:
function addDays(source, days) {
const copy = new Date(source.getTime());
copy.setDate(copy.getDate() + days);
return copy;
}
function addMonthsSafe(source, months) {
const copy = new Date(source.getTime());
const targetDay = copy.getDate();
copy.setDate(1); // 先置为 1 号,避免直接 setMonth 时提前溢出
copy.setMonth(copy.getMonth() + months);
// 计算目标月份的实际最大天数(下月第 0 天)
const maxDay = new Date(copy.getFullYear(), copy.getMonth() + 1, 0).getDate();
copy.setDate(Math.min(targetDay, maxDay));
return copy;
}
const jan31 = new Date(2026, 0, 31);
console.log(formatLocalDateTime(addDays(jan31, 7)).slice(0, 10));
console.log(formatLocalDateTime(addMonthsSafe(jan31, 1)).slice(0, 10));
console.log(formatLocalDateTime(jan31).slice(0, 10)); // 验证原对象未被修改
2026-02-07
2026-02-28
2026-01-31
操作 3:使用 toLocaleString 固定格式与时区展示
如果不想手写拼接函数,toLocaleString() 支持传入语言标记与配置项,并能显式指定 timeZone(如 'Asia/Shanghai')来保证不同地区用户看到统一时区的文本:
const utcMoment = new Date('2026-05-12T00:00:00Z');
const formatted = utcMoment.toLocaleString('zh-CN', {
timeZone: 'Asia/Shanghai',
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit',
second: '2-digit',
hour12: false
});
console.log(formatted);
2026/05/12 08:00:00
若需要更高频地批量格式化大量日期列表,建议改用 new Intl.DateTimeFormat('zh-CN', options).format(date),避免每次调用 toLocaleString() 都重新创建格式化器带来的额外开销。
五、方法选择与速查总结
面对具体需求时,可以按下面这张全景速查图快速定位合适的方法,同时核对对应的边界条件。
如果项目需要处理复杂的时区切换、工作日历或夏令时推算,在原生 Date 之外也可以评估轻量级日期库(如 date-fns、Day.js)或逐步关注现代浏览器推进中的 Temporal API;不过在常规业务里,只要把握住“单时间戳模型、字符串解析时区、month 零基索引、Setter 原地修改”这四条边界,原生 Date 已经足够清晰可靠。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。