做小程序开发的人估计都遇到过这种诡异时刻安卓上一切正常日期时间显示得清清楚楚一到iOS上就冒出来一个刺眼的NaN-NaN-NaN或者Invalid Date。尤其是涉及日期时间格式化封装Util的时候这个问题几乎人人都会踩一次。这篇就围绕一个自封的日期格式化工具类展开把iOS上显示为NaN的来龙去脉讲透把能直接复制进项目里的代码和规避方案整理出来适合正在做微信小程序、或者被日期格式化问题折腾到怀疑人生的同学参考。1. 先还原现场NaN是怎么跑到屏幕上的1.1 现象安卓没事iOS一到就错我最早碰到这个Bug是在一个订单列表页。后端接口返回的字段是createTime: 2024-06-18 14:30:00业务代码里也很自然地写了这么一段const date new Date(res.data.createTime); const text date.getFullYear() - (date.getMonth() 1) - date.getDate();安卓模拟器和真机上输出2024-06-18一切正常。结果测试同事拿着iPhone一打开页面上直接渲染出一排NaN-NaN-NaN。更气人的是这种报错不会在控制台打印任何异常因为new Date()不是抛错它只是静默地返回了一个 Invalid Date 对象。你后续调getFullYear()、getMonth()、getDate()全都在 NaN 的基础上继续算最后拼出来的字符串就是NaN-NaN-NaN。这种现象在时间选择器回显、聊天消息时间、订单倒计时这些场景里特别常见。因为它不是一进来就崩而是某些数据进到页面才触发排查起来很费劲。我当时先怀疑是数据格式不对打印出来看了半天字符串明明没问题又怀疑是getMonth()忘记加1但安卓是对的最后才锁定是 iOS 的new Date()解析问题。1.2 根因JavaScriptCore 与 V8 的日期解析差异这个问题的本质是 iOS 上微信小程序的 JS 引擎和安卓上的不一样。安卓系统上微信小程序的 JS 逻辑跑在 V8 引擎里和 Chrome 同源V8 对日期字符串的解析非常宽松。你给它2024-06-18 14:30:00它能在内部做各种容错猜测最后拼出一个有效的时间对象。而 iOS 上小程序用的是 JavaScriptCoreSafari 同款这个引擎对日期字符串的处理更死板基本只认符合规范的标准格式。像2024-06-18T14:30:00这种 ISO 格式它能解析但2024-06-18 14:30:00这种既带横线又带空格的默认后端时间格式JavaScriptCore 直接判死刑返回 Invalid Date。那为什么把横线换成斜杠就行了这也是实测踩出来的结论。new Date(2024/06/18 14:30:00)在 iOS 上是可以正常解析的斜杠分隔符是 iOS 能识别的格式。所以业内最常见的修复手段就是先把字符串里的-全部替换成/。还有一个隐蔽的坑要一起说纯日期字符串new Date(2024-06-18)在 iOS 上虽然不会返回 Invalid Date但会被当成 UTC 时间解析。在东八区getHours()会直接多出 8 小时。如果你对这种纯日期再做了HH的格式化就会得到一个诡异的时间偏移。这个坑单看现象很难想到是时区问题我在后面排查表里也会再列出来。2. 动手封装一个能救火的日期格式化Util2.1 为什么不直接引第三方库有人可能会问日期格式化这种需求直接引 dayjs 或者 moment 不是更省事吗为什么要自己封装一个我个人的判断是小程序场景下自己写一个几十行的工具类收益往往比引第三方库更大。第一是包体积小程序主包限制是 2MB虽然 dayjs 不算大但为了一个YYYY-MM-DD HH:mm:ss的格式化需求专门引一个依赖在团队评审时经常会被挑战。第二是兼容性dayjs 默认也是基于new Date()做解析直接传2024-06-18 14:30:00这种字符串在 iOS 上一样会踩 NaN 的坑你依然要自己先做字符串清洗并不省心。第三是 WXML 模板层的限制小程序里如果要在视图层直接格式化时间得用 WXS 脚本而 WXS 的语法能力有限第三方库很难原样搬进去。所以我的结论很明确如果你的项目只用到基础的时间格式化、相对时间、时长转换手写一个 Util 是最稳定、最容易控制、也最好排查问题的方案。2.2 工具类整体设计思路这个工具类的核心设计思路只有一句话把所有字符串转 Date的入口收拢到一个函数里。传统写法的毛病在于业务代码里到处直接new Date(someString)一旦 iOS 解析失败你需要在每个调用点去排查。而封装后的写法是所有调用方都不直接碰new Date()统一交给parseDate()先做安全解析解析得到一个有效的 Date 对象后格式化函数只管在 Date 上取值拼接。这样设计有三个直接好处排查问题只需要看parseDate一个入口不用满项目搜索new Date。后端如果换了时间字段格式比如从带横线变成 ISO 带毫秒只需要在parseDate里加一个分支。不管是 Date 对象、13位毫秒时间戳、10位秒级时间戳还是各种字符串格式调用方拿到的始终是一个可靠的 Date 对象。这个思路其实挺像后端常用的防腐层概念不让外部千奇百怪的格式直接影响核心逻辑在边界处统一做转换。3. 核心代码实现与逐行说明3.1 安全解析坑最深的入口先上parseDate的完整代码。这个函数是整个工具类的地基后面所有格式化函数都依赖它// utils/dateUtil.js function parseDate(input) { // 已经是 Date 实例的情况 if (input instanceof Date) { return isNaN(input.getTime()) ? null : input; } // 数字兼容毫秒时间戳和秒级时间戳 if (typeof input number) { if (String(input).length 10) { return new Date(input * 1000); } return new Date(input); } // 字符串 if (typeof input string) { let str input.trim(); // 兼容 ISO 字符串里的 T 分隔符 str str.replace(T, ); // 关键一步iOS 不识别 -统一替换成 / str str.replace(/-/g, /); // 手动拆解 yyyy/MM/dd HH:mm:ss 以及子集 const match str.match(/^(\d{4})\/(\d{1,2})\/(\d{1,2})(?:\s(\d{1,2}):(\d{1,2})(?::(\d{1,2}))?)?$/); if (match) { const [, y, m, d, hh 0, mm 0, ss 0] match; return new Date(y, m - 1, d, hh, mm, ss); } // 剩下的交给原生 Date 兜底 const date new Date(str); return isNaN(date.getTime()) ? null : date; } return null; }逐个说一下关键点。第一行input instanceof Date的判断很重要。有些业务代码在拿到时间后可能已经在别处转成了 Date 对象这时候如果再做字符串 replace 反而会出错直接返回原对象最安全。同时还要检查它是否有效因为new Date(xx)构造出来的 Invalid Date它的类型确实是Date但getTime()是 NaN必须拦下来。数字分支这里我特别处理了10位时间戳。后端接口返回时间戳时有的给毫秒级13位有的给秒级10位如果不判断直接new Date(1718700000)得到的时间是 1970 年格式化出来一屏幕诡异数字。判断逻辑就是看字符串长度10位就乘 1000。字符串分支里的前三行基本可以解决 iOS 上 90% 的 NaN 问题trim()处理字符串前后可能存在的空格和换行。replace(T, )把 ISO 格式里的T统一成空格让后面的正则好处理。replace(/-/g, /)就是经典的 iOS 兼容替换所有横线换斜杠。正则手动拆解这一步是整个函数的灵魂。它的好处是完全绕开了 iOS 的日期字符串解析引擎直接用数值型构造函数new Date(y, m - 1, d, hh, mm, ss)。这种构造函数传参会把数值作为本地时间理解在 iOS 和安卓上的表现完全一致不存在时区偏移和格式歧义问题。比如2024-06-18 14:30:00经过 replace 后变成2024/06/18 14:30:00正则捕获到y2024, m06, d18, hh14, mm30, ss00然后new Date(2024, 5, 18, 14, 30, 0)得到一个准确的本地时间对象。3.2 格式化主函数 formatDateparseDate 稳定之后格式化就非常简单了function formatDate(input, fmt YYYY-MM-DD HH:mm:ss) { const date parseDate(input); if (!date) return ; const pad (n) (n 10 ? 0 n : n); const o { YYYY: date.getFullYear(), MM: pad(date.getMonth() 1), DD: pad(date.getDate()), HH: pad(date.getHours()), mm: pad(date.getMinutes()), ss: pad(date.getSeconds()), }; return fmt.replace(/YYYY|MM|DD|HH|mm|ss/g, (k) o[k]); }这个函数把模板字符串里的YYYY、MM、DD、HH、mm、ss依次替换成实际值。pad是一个补零函数月份、日期、时分秒小于10的时候在前面补一个0这样显示出来是2024-06-18而不是2024-6-18视觉上整齐很多。有几个细节要特别提醒。第一个是getMonth()必须加 1。JS 的月份从 0 开始10月是 9如果忘记加1所有月份都会慢一个月。这是新手最容易犯的错没有之一。第二个是模板大小写约定。我这里统一用大写YYYY表示年份大写MM表示月份大写DD表示日期大写HH表示24小时制小时小写mm表示分钟小写ss表示秒。为什么不直接用后端常用的yyyy-MM-dd因为yyyy和YYYY混用会让实现变复杂团队协作时也容易踩坑。统一一套约定写到项目文档里后面的人照着用就行。调用示例formatDate(2024-06-18 14:30:00, YYYY年MM月DD日 HH:mm); // 2024年06月18日 14:30 formatDate(2024-06-18, MM-DD); // 06-18 formatDate(1718700000000, YYYY/MM/DD); // 2024/06/18 formatDate(2024-06-18 14:30:00); // 2024-06-18 14:30:00如果传入的是一个无法解析的值比如空字符串或者不合法的字符串parseDate返回 nullformatDate直接返回空字符串。这样页面上最多显示一个空白不会出现一排NaN。3.3 形态补充时长格式化与相对时间工具类顺手多做两个高频函数能省下不少业务代码。一个是formatDuration把毫秒数转成HH:mm:ss做视频时长、录音时长、订单倒计时都很好用function formatDuration(ms) { const total Math.floor(ms / 1000); const hh Math.floor(total / 3600); const mm Math.floor((total % 3600) / 60); const ss total % 60; const pad (n) (n 10 ? 0 n : n); return pad(hh) : pad(mm) : pad(ss); }思路很简单先把毫秒转成总秒数然后分别算出小时、分钟、秒。注意Math.floor一定要用否则毫秒数不足一秒时会出现小数秒显示00:00:00.5这种奇怪结果。另一个是getRelativeTime做聊天列表、消息通知里的刚刚 / 5分钟前 / 3小时前 / 2天前function getRelativeTime(input, now Date.now()) { const date parseDate(input); if (!date) return ; const diff now - date.getTime(); const minute 60 * 1000; const hour 60 * minute; const day 24 * hour; if (diff minute) return 刚刚; if (diff hour) return Math.floor(diff / minute) 分钟前; if (diff day) return Math.floor(diff / hour) 小时前; return Math.floor(diff / day) 天前; }这个函数会先走一遍parseDate确保入参安全然后计算当前时间和目标时间的差值。如果差值是负数也就是遇到未来时间需要业务侧自己判断比如直接返回刚刚或者做绝对值处理。这个我在踩坑记录里会再提一句。4. 在项目里落地的姿势4.1 模块导出与页面调用工具类写完在文件底部导出module.exports { parseDate, formatDate, formatDuration, getRelativeTime, };页面里用 CommonJS 的方式引入const dateUtil require(../../utils/dateUtil); Page({ data: { orderTime: 2024-06-18 14:30:00, showTime: , }, onLoad() { this.setData({ showTime: dateUtil.formatDate(this.data.orderTime, YYYY-MM-DD HH:mm), }); }, });我个人的习惯是在数据进入页面时就完成格式化把它作为新的展示字段存到data里而不是在事件回调里现场格式。比如接口返回一个列表我会用map遍历一次const list rawList.map((item) ({ ...item, createTimeText: dateUtil.formatDate(item.createTime, YYYY-MM-DD HH:mm), })); this.setData({ list });这样做的好处是WXML 模板里不需要做任何逻辑处理直接渲染item.createTimeText就行。而且格式化的结果稳定不会因为后续操作导致重复计算。缺点是每条数据多了一个字段但这对小程序的内存占用来说几乎可以忽略。4.2 WXML 里格式化WXS 的正确姿势有一种情况绕不开 WXML 层直接格式化你的列表数据已经渲染出来又不想在 setData 之前循环处理或者有些字段是动态传入的。这时可以借助微信小程序的 WXS 模块。需要注意WXS 不是普通的 JS它运行在视图层语法只支持 ES5 的绝大部分特性不支持解构赋值、箭头函数、模板字符串这些 ES6 语法也不能直接 require 上面那个dateUtil.js。所以要单独维护一份.wxs文件。我在utils/dateUtil.wxs里放了一个精简版// utils/dateUtil.wxs function formatDate(input, fmt) { if (!input) return ; // 兼容 iOS横线替换为斜杠 var str String(input).replace(/-/g, /); var date getDate(str); if (!date) return ; var pad function (n) { return n 10 ? 0 n : n; }; var o { YYYY: date.getFullYear(), MM: pad(date.getMonth() 1), DD: pad(date.getDate()), HH: pad(date.getHours()), mm: pad(date.getMinutes()), ss: pad(date.getSeconds()), }; for (var key in o) { fmt fmt.split(key).join(o[key]); } return fmt; } module.exports { formatDate: formatDate, };在 WXML 里这样引用wxs src/utils/dateUtil.wxs moduledateUtil / view{{dateUtil.formatDate(item.createTime, YYYY-MM-DD)}}/view这里有两个实测心得。第一个是 WXS 里没有new Date()但提供了内置的getDate()函数用法和 JS 里的Date构造类似。所以最稳的写法就是先把横线替换成斜杠再交给getDate解析。第二个是循环替换用了fmt.split(key).join(o[key])而不是fmt.replace(/YYYY/g, ...)。原因是 WXS 对正则 replace 的支持在不同基础库版本上表现不太一致split和join是最稳妥的字符串替换方案。实测下来这种方式在 iOS 真机上没有任何问题。4.3 三种典型场景的格式化配置不同业务场景的展示格式差别很大我这里整理了一个常用对照场景入参类型格式化模板结果示例订单创建时间2024-06-18 14:30:00YYYY-MM-DD HH:mm:ss2024-06-18 14:30:00日期选择器回显2024-06-18YYYY-MM-DD2024-06-18聊天会话时间13位时间戳MM-DD HH:mm06-18 14:30消息提醒角标10位时间戳relative相对时间3小时前视频/录音时长毫秒数formatDuration01:26:05这里面比较容易被忽略的是日期选择器回显。比如某个业务给用户展示一个默认日期后台返回的是2024-06-18这种纯日期字符串。如果直接new Date(2024-06-18)在 iOS 上虽然不会变成 NaN但解析成 UTC 时间后再配合日期选择器的value绑定可能出现日期偏移。用封装里的 parseDate 走正则拆解路径返回的是本地时间就不会有这个问题。5. 踩坑记录与排查速查表5.1 常见问题排查表把我和身边同事踩过的坑整理成一张速查表建议收藏症状可能原因解决办法iOS 显示NaN-NaN-NaN字符串2024-06-18 14:30:00直接new Date先replace(/-/g, /)再解析或直接用 parseDateiOS 时间多了 8 小时纯日期2024-06-18被按 UTC 解析用正则拆解后new Date(y, m-1, d)手动构造getYear返回 124用了getYear()而不是getFullYear()统一使用getFullYear()格式化后年份是 197010位秒级时间戳没乘 1000判断字符串长度10位补乘 1000WXML 里格式化方法不生效WXML 不认 JS 函数提前 setData或使用 WXS 模块格式化后月份少 1getMonth()从 0 开始统一getMonth() 1字符串前后有空格导致解析失败后端数据带换行或缩进parseDate 里先trim()相对时间出现负数目标时间在未来业务侧对 diff 做判断返回刚刚或绝对值5.2 两个后来才想明白的隐形坑除了上面这些能一眼看出的问题还有两个坑是我后来才彻底想明白的。第一个是看起来一样、实际不一样的字符串。有些后端返回的时间字符串肉眼看起来是2024-06-18 14:30:00但其中可能混入了全角字符或者特殊空格导致替换和解析都失效。我遇到过一位同事把字符串打印出来查了半天最后用charCodeAt逐字检查才发现中间有一个不间断空格。所以在 parseDate 里先trim()后续实在解析不了就返回 null让前端至少显示空而不是 NaN。第二个是带 Z 后缀的 UTC 字符串。类似2024-06-18T14:30:00.000Z这种格式 iOS 和安卓都能解析但它表示的是 UTC 时间。如果你直接格式化输出国内用户看到的就是东八区偏移后的时间。这个不算 Bug但要跟后端对齐语义如果后台存的是 UTC 时间前端格式化时要么手动加 8 小时要么用getUTCFullYear系列方法如果后台拼的其实是想表达的本地时间只是错误地加了 Z 后缀那就需要找后端修正。这里最容易出问题的是双方都以为对方处理了时区。5.3 排查思路沿着数据链路看最后分享一个排查这类问题的通用思路遇到日期相关 Bug我习惯沿着数据链路一层层看。第一步确认数据源头。打日志看接口返回的到底是字符串、时间戳还是 Date 对象字段格式长什么样。这一步能过滤掉一半问题。第二步确认代码有没有走 parseDate。很多项目的代码是先在业务层new Date()了一次然后把 Date 对象传给了格式化函数这时候 parseDate 里的字符串兼容逻辑根本不会触发。所以排查时先搜一下项目里有没有裸new Date调用尤其是直接new Date(某字符串)的地方。第三步确认格式化模板和大小写。YYYY和yyyy、MM和mm如果混用替换函数匹配不到对应的 key输出就会原样保留模板占位符看起来像2024-MM-18这种半成品。第四步上真机验证。这一点必须强调开发者工具用的是电脑上的 V8 引擎很多日期格式在工具里完全正常一上 iOS 真机立刻现出原形。所以只要涉及日期格式化无论改了什么最后都一定拿 iPhone 真机跑一遍列表页、详情页和带倒计时的页面。实测下来这一步能拦住百分之九十九的回归问题。最后再唠叨一句经验之谈。日期时间格式化这个需求看起来小可它藏着的坑绝不比一个复杂页面少。与其在业务代码里到处写new Date、到处 replace不如花半小时把 Util 封装好让所有日期解析和格式化都走同一个入口。后面不管遇到 iOS 的 NaN还是时区偏移、时间戳位数问题都能在一处定位、一处修复。这套代码拿去直接放进项目就能跑重点用 iPhone 真机验证三个最常出现日期的页面。如果你们在实际项目中遇到过其他奇葩的日期问题也欢迎把场景抛出来一起交流。