JS时间戳转换出现NaN或Invalid Date怎么办

图 1：JavaScript 时间戳转换异常状态流转图（输入源、解析分支与最终状态）

一、为什么会出现 NaN 与 Invalid Date

在开始修复之前，需要先厘清两个典型报错在 JavaScript 运行机制中的具体区别：

• Invalid Date（非法日期实例）：这是一个合法的 Date 对象实例，但其内部保存的时间戳数值为 NaN。当我们在控制台打印它，或者调用 toISOString() 等转换方法时，引擎会抛出异常或输出字符串 "Invalid Date"。
• NaN（非数值计算结果）：通常出现在试图从非法 Date 对象中提取数值时。例如调用 date.getTime()、date.getFullYear()，或者用 +date 进行隐式数值转换，由于内部底层数值本身已损坏，返回的结果便直接变成了 NaN。

很多开发者在排查时容易被“开发机上正常、线上或移动端报错”所困惑。造成这种差异的根本原因，在于 ECMAScript 规范中对 new Date(value) 的参数处理规则：当传入数字时，引擎直接将其作为自 1970 年元旦起的毫秒数；而一旦传入的是字符串（哪怕是纯数字组成的字符串 "1715000000000"），引擎会转而调用 Date.parse()。V8 引擎（Chrome、Node.js）对非标准格式有较宽泛的容错，但 WebKit（Safari、iOS 微信内置浏览器）则严格遵循规范，无法把纯数字字符串当成合法的 RFC2822 或 ISO 8601 日期，从而直接生成 Invalid Date。

二、系统排查与四步修复法

按照发生概率从高到低，建议依次执行以下四个排查步骤，定位并修复问题：

图 2：时间戳异常排查与修复决策流程图（空值、类型、精度与校验）

第 1 步：排查是否传入了“字符串类型”的时间戳

接口返回的数据往往经过了 JSON 序列化，有时后端或中间件为了防止 64 位大整数在前端溢出（如长整型 ID 或雪花算法时间戳），会以字符串形式输出时间戳（例如 "1715000000000"）。如果在前端没有显式转换，直接调用 new Date(str)，就会在部分终端上暴露出兼容性缺陷。

// ❌ 存在跨浏览器隐患的写法
const raw = "1715000000000";
const date = new Date(raw); // Chrome 可能正常解析，Safari 则返回 Invalid Date

// ✅ 显式数值转换修复写法
const num = Number(raw);
const safeDate = new Date(num);

第 2 步：核对时间戳位数（10 位秒级 vs 13 位毫秒级）

不同技术栈的时间戳单位约定不同。PHP、Python、Go 及 MySQL 原生函数（如 UNIX_TIMESTAMP()）默认输出的是以“秒”为单位的 10 位时间戳（例如 1715000000）；而 JavaScript 原生 Date 接收的必须是以“毫秒”为单位的 13 位数值。

如果将 10 位时间戳直接传给 new Date(1715000000)，JavaScript 会将其当作 17 亿毫秒，换算出来的时间大约仅是 1970 年 1 月 20 日，造成界面上显示为 1970 年的历史错误；若再结合某些字符串格式化库的严格区间检测，还会直接返回 Invalid Date。

// 判断是否为 10 位时间戳并补齐毫秒
let timestamp = Number(input);
if (String(Math.floor(timestamp)).length === 10) {
  timestamp = timestamp * 1000;
}
const targetDate = new Date(timestamp);

第 3 步：防御 null、undefined 与空字符串渗透

在异步数据加载、组件首次挂载或接口字段缺省时，传入时间转换函数的值极有可能是 undefined、null 或 ""。不同异常值在 JS 中的隐式转换各不相同：

• new Date(undefined)：立即返回 Invalid Date，后续取值全为 NaN；
• new Date("")：直接返回 Invalid Date；
• new Date(null)：这是最隐蔽的陷阱！因为 Number(null) === 0，JavaScript 会将其认定为合法的纪元起点，解析成 1970-01-01 08:00:00，不会报错却导致脏数据悄然入库。

因此，在进入解析前必须设置显式的非空前置条件：

// 严密的前置非空拦截
if (input === null || input === undefined || input === "") {
  return null; // 或者返回指定的兜底占位文本，如 "--"
}

第 4 步：使用 isNaN(date.getTime()) 进行终验

不要使用 if (date) 或 typeof date === "object" 来判断转换是否成功。在 JavaScript 中，即便 Date 实例已经损坏（Invalid Date），其类型依然是 object，布尔值判定依然为 true。

业内标准的有效性终验方法是利用其内部时间戳。通过调用 date.getTime() 并配合全局的 Number.isNaN() 判定：

function isValidDate(d) {
  return d instanceof Date && !Number.isNaN(d.getTime());
}

三、深入底层：10 位与 13 位时间戳及浏览器解析差异

要彻底避免时间计算中的异常，需要理解 ECMAScript 规范中对时间戳的设计考量。

图 3：10位秒级与13位毫秒级时间戳结构与解析规范对比

ECMAScript 规范明确规定，Date 对象的内部存储为一个表示毫秒值的 Number 类型数值。它的时间基准为 UTC 1970 年 1 月 1 日 00:00:00。现代常见的 Unix 时间戳采用秒为计量单位，十位数字大致覆盖从 2001 年到 2038 年（受 32 位整型溢出限制）。而在前端生态中，所有原生时间 API（如 Date.now()、(new Date()).getTime()）统一按 13 位毫秒计数。

当开发者将一个 10 位的数值通过字符形式传入 new Date("1715000000") 时，WebKit 引擎会根据标准去匹配诸如 YYYY-MM-DDTHH:mm:ss.sssZ 的语法树，由于既没有破折号分隔也没有合法月份区间，匹配器直接判定语法非法，输出 Invalid Date。而在 Chrome 的 V8 引擎中，为了兼容历史网页，内部增加了非标准回退逻辑，甚至会尝试将部分纯数字字符串转换为数字。这种引擎层面的宽容度差异，正是本地开发正常但移动端频繁崩溃的罪魁祸首。

四、生产级通用防御转换函数

在企业级开发中，不应把这些零散的判断散落在业务代码各处，而应封装一个安全、无外部依赖的高可用转换工具函数：

/**
 * 安全解析时间戳为 Date 实例
 * @param {number|string|Date} input - 原始时间戳或日期输入
 * @param {Date|null} [fallback=null] - 解析失败时的降级回退值
 * @returns {Date|null} 解析成功的 Date 对象或 fallback
 */
function safeParseDate(input, fallback = null) {
  // 1. 拦截空值与非法类型
  if (input === null || input === undefined || input === "") {
    return fallback;
  }

  // 2. 如果本身已是合法 Date 实例，直接返回
  if (input instanceof Date) {
    return Number.isNaN(input.getTime()) ? fallback : input;
  }

  // 3. 去除字符串前后空格并显式转换为数值
  const cleanInput = typeof input === "string" ? input.trim() : input;
  const num = Number(cleanInput);

  // 4. 判断转换后是否为有效数值（过滤非纯数字文本）
  if (Number.isNaN(num)) {
    return fallback;
  }

  // 5. 自动识别位数：10位秒级时间戳扩充为13位毫秒
  let normalizedMs = num;
  const intStr = String(Math.floor(Math.abs(num)));
  if (intStr.length === 10) {
    normalizedMs = num * 1000;
  }

  // 6. 构造 Date 实例并做最终合法性检验
  const parsedDate = new Date(normalizedMs);
  if (Number.isNaN(parsedDate.getTime())) {
    return fallback;
  }

  return parsedDate;
}

五、常见报错场景与避坑速查

为了便于日常开发中快速定位，下表与图示总结了五大常见的时间戳异常场景及其对应的标准解法：

图 4：时间戳转换常见异常与解决方案速查对比图

总结而言，排查 JS 时间戳转换中的 NaN 与 Invalid Date，关键在于放弃对浏览器隐式类型转换的依赖。在将数据送入 new Date() 之前，坚持做到“先防空、后转数、补齐位、验有效”，即可保证时间处理在 Chrome、Safari、移动端 WebView 等所有运行环境中稳定可靠。