微信小程序开发中日期时间格式化几乎是每个项目逃不开的环节。不管是列表页展示“刚刚 / 5分钟前”还是订单详情需要“2024-05-20 14:30:00”这种标准格式都得跟日期字符串打交道。我在实际开发中发现很多初学者直接拿原生Date对象拼接字符串看起来很省事一旦遇到 iOS 设备页面就悄无声息地出现一堆NaN查起来又隐蔽又烦人。这篇文章就把我在微信小程序里封装日期时间格式化工具的全过程、iOS 上 NaN 问题的根因和修复方案以及常用的避坑经验一次性讲透。如果你正在写小程序或者刚接触前端日期处理这篇文章可以直接帮你少走弯路。我会从工具设计思路讲起给出可以直接抄作业的util.js封装代码再深入到 iOS 的 JavaScriptCore 引擎差异和兼容处理最后整理一份常见问题排查清单。整套方案我已经在多个微信小程序项目里验证过兼容性、可维护性都比散落在页面里的Date操作强很多。1. 为什么需要自定义日期格式化工具1.1 原生能力在小程序里的尴尬处境微信小程序和普通网页最大的区别在于运行环境。小程序的逻辑层跑在 JavaScriptCoreiOS或 V8Android上虽然 ES6 的Date方法基本都支持但实际用起来有几个问题绕不过去。第一个问题是Date.prototype.toISOString()、toLocaleString()这类方法在不同系统上返回的格式不一致。比如toLocaleString()在 iOS 上可能返回2024/5/20 14:30:00在 Android 上返回2024/05/20 14:30直接拿去展示会出现布局抖动用户肉眼可见地觉得不协调。第二个问题是 iOS 对日期字符串的解析规则非常特殊new Date(2024-05-20 14:30:00)这种带横杠的格式在 iOS 上解析失败得到的是Invalid Date后续任何.getTime()、.getFullYear()操作都会得到NaN。第三个问题是业务场景往往需要“个性化格式”。展示端要YYYY-MM-DD接口传输要时间戳日志要YYYY-MM-DD HH:mm:ss分享卡片要MM月DD日一个原生Date对象根本覆盖不了这么多种格式。其实不只是小程序很多混合开发和 Web 项目也会遇到类似问题但小程序里因为涉及机型碎片化和 WebView 差异问题被放大了。与其每个页面各写一套处理逻辑不如在项目初期就封装一个统一的日期时间格式化工具所有页面统一调用以后哪怕要改格式、加时区、做国际化都只改一个文件。1.2 工具库的基本设计思路我在设计这个工具时定位非常明确不需要做成像 moment.js 那样的大而全但要满足日常 90% 的业务场景同时保持代码体积小、无依赖、可读性强。因为我做的是小程序包体积直接影响首屏加载速度引入一个 60KB 以上的日期库有点得不偿失。核心功能拆开来看只需要三部分输入归一化接收时间戳、日期字符串、Date对象内部统一转成合法的Date对象格式化核心根据传入的模板字符串比如YYYY-MM-DD HH:mm:ss输出对应的时间文本增强辅助相对时间多久以前、补零、时区处理这些属于常见附带需求。比如我在业务里见过一种典型场景后端返回2024-05-20T14:30:00.000Z这种带时区的 ISO 字符串前端拿到后直接new Date()在 Android 上正常显示在 iOS 上就变成NaN。工具类必须在输入层就做兼容不能等到格式化时才暴露问题。设计好需求边界之后再动手写代码思路就清晰了。2. 工具类型封装与核心实现2.1 工具函数签名与参数解释直接上一个精简版的util.js兼容微信小程序 CommonJS 模块规范。函数签名我采用formatDate(date, fmt)其中date支持三种类型数字、字符串、Date实例fmt是字符串模板默认给一个全量格式。// utils/date.js /** * 日期时间格式化工具 * 支持输入时间戳(毫秒/秒)、日期字符串、Date 对象 * 支持模板YYYY MM DD HH mm ss SSS * 示例 * formatDate(1716193200000, YYYY-MM-DD HH:mm:ss) * formatDate(2024-05-20 14:30:00, YYYY年MM月DD日) */ function formatDate(date, fmt YYYY-MM-DD HH:mm:ss) { if (!date) return ; // 1. 输入归一化统一转成 Date 对象 const d normalizeDate(date); if (!d) { console.warn([formatDate] invalid date:, date); return ; } // 2. 模板匹配与替换 const o { YYYY: d.getFullYear(), MM: pad2(d.getMonth() 1), DD: pad2(d.getDate()), HH: pad2(d.getHours()), mm: pad2(d.getMinutes()), ss: pad2(d.getSeconds()), SSS: pad3(d.getMilliseconds()), YY: String(d.getFullYear()).slice(2) }; return fmt.replace(/YYYY|MM|DD|HH|mm|ss|SSS|YY/g, (match) o[match]); } function normalizeDate(date) { if (date instanceof Date) { return isNaN(date.getTime()) ? null : date; } if (typeof date number) { // 兼容秒级时间戳10位数字默认当作秒13位当作毫秒 const ts date 100000000000 ? date * 1000 : date; const d new Date(ts); return isNaN(d.getTime()) ? null : d; } if (typeof date string) { // 重点iOS 兼容处理见 3.2 节 const normalizedStr date.replace(/-/g, /); const d new Date(normalizedStr); return isNaN(d.getTime()) ? null : d; } return null; } function pad2(n) { return n 10 ? 0 n : n; } function pad3(n) { if (n 10) return 00 n; if (n 100) return 0 n; return n; } module.exports { formatDate };这段代码里有几个我在实际项目中沉淀下来的细节值得单独说明一下。normalizeDate里对数字做了 10 位/13 位时间戳的自动判断。因为有些后端接口返回的是1716193200秒有些返回1716193200000毫秒不做兼容的话秒级时间戳换算出来是 1970 年附近的时间页面一出来就是一堆奇怪的日期。我见过不止一次因为这种低级错误排查半天的案例。10 位时间戳统一乘 1000这个处理对业务来说几乎是零成本的。pad2和pad3用来补零。这里不用String.prototype.padStart一方面是为了兼容更老的基础库另一方面也是因为手写这几个函数对性能影响微乎其微但可读性很强。如果你用的是比较新的编译器用padStart也不会有问题只是我习惯了这种写法不容易踩兼容性的坑。2.2 格式化模板的匹配与替换原理很多同学看到replace(/YYYY|MM|DD|HH|mm|ss|SSS|YY/g, ...)这行可能觉得不就是字符串替换嘛但这里藏着一个小坑正则表达式的匹配顺序。我故意把YYYY放在YY前面否则当你写YYYY时YY模式会先命中替换成两位年份剩下的YY就变成纯数字拼凑输出就完全错了。正则的全局匹配是replace默认从左到右扫描的哪个分支先匹配就看正则里的顺序。所以模板替换这行看起来简单实际是隐患集中地。还有个小细节fmt.replace(...)用了函数式回调而不是直接o[match]拼接这样就算某个模板字符没在o里定义也只是保持原样不会因为访问undefined导致报错。接下来补充一个日常常用的相对时间函数我一般叫fromNow。这个函数负责把过去的时间点转成刚刚、x分钟前、x小时前、x天前这种文案非常适合消息列表、评论列表、动态流。function fromNow(date) { const d normalizeDate(date); if (!d) return ; const diff Date.now() - d.getTime(); if (diff 0) return 刚刚; const minute 1000 * 60; const hour minute * 60; const day hour * 24; const month day * 30; const year day * 365; if (diff minute) return 刚刚; if (diff hour) return Math.floor(diff / minute) 分钟前; if (diff day) return Math.floor(diff / hour) 小时前; if (diff month) return Math.floor(diff / day) 天前; if (diff year) return Math.floor(diff / month) 个月前; return Math.floor(diff / year) 年前; }这个fromNow看起来不复杂但我提醒一句如果你的项目涉及“未来时间”比如活动倒计时、预约时间这里diff 0直接返回刚刚是合理的产品逻辑不要在这个分支里做复杂的绝对值倒计时那是另一个函数该干的事。别把职责混在一起。2.3 时间戳、日期字符串与 Date 对象的兼容处理理论上工具应该让调用方根本不用关心传入的是什么类型但现实中总会遇到几个极端情况。比如后端把日期字段传成null、空字符串或者null字符串又比如因为序列化问题时间戳变成浮点数或者带单位后缀的字符串。我习惯在工具里做一层“脏数据处理”。上面代码里if (!date) return 处理了null、空串、0、false这些 falsy 值。但这里有个容易忽略的点如果传入的时间戳正好是0那这个判断也会把它拦截掉。虽然业务上几乎不会出现“1970-01-01”这种需求但如果你要做一个历史纪元相关的小工具就得额外区分date 0的场景。我目前的做法是业务上一个约定时间戳为 0 当作无值处理。normalizeDate对字符串的解析用的是date.replace(/-/g, /)这背后是 iOS 兼容的核心但只替换-为/还不够。遇到带T和Z的 ISO 字符串怎么办我在项目里是先把T替换成空格再剥离Z保证new Date能解析。类似let normalizedStr date.trim().replace(/-/g, /).replace(T, ).replace(/\.\dZ?$/g, ); let d new Date(normalizedStr);实际测试中new Date(2024/05/20 14:30:00)在 iOS、Android、微信开发者工具上都能正常解析。而new Date(2024-05-20T14:30:00.000Z)在 iOS 上也存在解析风险所以这种 ISO 字符串最好先统一转换。遇到iOS上的new Date(2024/5/20 14:30:00)有时也会出现月份/日期缺 0 导致解析偏差我的建议是如果接口能控制格式定死补零如果不能工具里可以在解析后检查getMonth()是否为 NaN。3. iOS 上显示 NaN 的根因分析与修复方案3.1 iOS JavaScriptCore 对日期字符串的解析差异这个问题可以说是微信小程序开发里最高频的 iOS 专属 bug 之一。线上环境 iOS 显示NaN-NaN-NaN但开发者工具和 Android 真机一切正常。不少同学第一反应是“微信缓存问题”清了缓存、重新编译还是 NaN最后才发现是new Date()解析差异。iOS 的 JavaScriptCore 引擎对日期字符串的处理有严格的格式要求。它并不支持YYYY-MM-DD HH:mm:ss这种带空格和横杠的字符串而是更倾向于/分隔的格式例如2024/05/20 14:30:00。而 Android 的 V8 引擎适配能力更强-格式也能正确识别。这种差异本质是引擎规范实现不同不是小程序框架的问题。还有一个隐藏的细节即使都是 iOS不同系统版本的 JavaScriptCore 行为也有细微差别。低版本 iOS 对new Date(2024/05/20 14:30:00)这种本地时间格式支持还好但对 ISO 8601 带时区的字符串支持得参差不齐。所以我的原则是工具里所有字符串日期一律先转成/分隔的本地时间格式再丢给new Date不给引擎发挥的空间。3.2 修复方案与代码改造修复的核心思路就一句话在创建Date对象之前把输入日期统一转成 iOS 能识别的格式。function normalizeDate(date) { if (typeof date string) { let dateStr date.trim(); // 处理 ISO 格式2024-05-20T14:30:00.000Z dateStr dateStr.replace(T, ).replace(/\.\d{3}Z?$/, ); // 核心修复横杠转斜杠 dateStr dateStr.replace(/-/g, /); const d new Date(dateStr); return isNaN(d.getTime()) ? null : d; } // ... 其他类型 }我单独提一下时区问题。如果你直接把2024-05-20T14:30:00.000Z的T替换成空格、去掉Z那得到的其实是 UTC 时间文本在new Date解析时会被当作本地时间这就产生了时差。如果业务上希望显示北京时间需要先把 UTC 时间做偏移。我当时在某个国际业务里就被这个坑折腾了很久。简单稳妥的做法是function parseDateString(input) { // 输入形如 2024-05-20T14:30:00.000Z const d new Date(input); if (!isNaN(d.getTime())) return d; // 兜底替换分隔符 const normalized input.replace(/-/g, /).replace(T, ).replace(.000Z, ); return new Date(normalized); }你会发现new Date(originalISOString)在很多地方其实是能解析的iOS 的问题主要出在“非 ISO 的自定义格式”。所以我的兜底策略是先尝试标准解析失败后再做分隔符替换。这样既兼容了 ISO又解决了YYYY-MM-DD HH:mm:ss格式在 iOS 上的NaN。3.3 对应兼容方案同一天同一秒会出现的边界问题修复过程中我遇到过很多奇奇怪怪的边界场景单独列一节想清楚。最常见的几个日期格式为2024-5-20 14:30:00也就是月份和日期没补零。这种字符串在某些浏览器能解析在 iOS 上会得到Invalid Date。我的方案是做一个正则强制补零function padDateParts(str) { return str.replace(/(\d{4})[-/](\d{1,2})[-/](\d{1,2})/, (match, y, m, d) { return y / pad2(m) / pad2(d); }); }你看这个正则匹配到了年、月、日然后把月、日分别补成两位。虽然大多数时候后端不会返回这种数据但用户输入、URL 参数传参时经常碰到。我就在某个活动页的分享参数里见过date2024-5-2这种值真是防不胜防。日期字符串里混入了中文比如2024年05月20日 14:30:00。这通常出现在从某个页面复制过来的参数里。处理方式是把中文分隔符替换成/dateStr dateStr.replace(/年|月/g, /).replace(/日/g, );时间戳为字符串比如1716193200000。如果直接走字符串解析new Date(1716193200000)在 iOS 上也会得到 Invalid Date在 Android 上反而是正常的。所以normalizeDate里要对这种纯数字字符串做一次判断转成 number 类型再处理。这些边界问题单独看都不算起眼但组合在一起的时候如果工具里没有统一处理每个页面都得补一套防御代码代码就会变得又臭又长。集中处理的价值就在这里。4. 跨平台测试与实战避坑4.1 测试用例设计一套用例打遍三端工具写好之后测试用例设计直接决定了上线的安心程度。我习惯把测试用例分成四类合法输入类、边界输入类、非法输入类、平台差异类。合法输入类很简单传时间戳、ISO 字符串、普通日期字符串看输出是否等于预期。边界输入类包括最小值、最大值、闰年、跨月、跨年。非法输入类包括null、空字符串、undefined、乱码字符串。平台差异类专门用 iOS 和 Android 真机各跑一遍。实际测试中我遇到过这样一组用例输入期望输出开发者工具Android 真机iOS 真机formatDate(1716193200000, YYYY-MM-DD HH:mm:ss)2024-05-20 14:30:00通过通过通过formatDate(2024-05-20 14:30:00, YYYY-MM-DD HH:mm:ss)2024-05-20 14:30:00通过通过需要修复formatDate(2024-05-20T14:30:00.000Z, YYYY-MM-DD HH:mm:ss)视时区策略而定通过通过需要修复formatDate(2024-5-20 14:30:00, YYYY-MM-DD HH:mm:ss)2024-05-20 14:30:00通过通过需要修复这个表格很直观地说明一个问题很多问题在开发者工具和 Android 上看不出来必须用 iOS 真机验证。开发者工具的 JS 环境是浏览器 V8对日期宽容度高所以很多人开发时根本没发现 bug一发布就被用户骂。4.2 已知常见问题排查与注意事项根据我过去踩过的坑整理一份排查清单供你参考场景 1页面显示NaN-NaN-NaN优先检查传入的日期字符串格式。如果是YYYY-MM-DD HH:mm:ss先replace(/-/g, /)再new Date。如果还不行打印一下normalizeDate的结果确认是否是Invalid Date对象。场景 2时间差 8 小时大概率是时区问题。接口返回带Z的 UTC 时间前端没做时区转换。我在工具里增加了一个参数offsetHours默认按本地时间展示。如果你明确要展示北京时间要小心用户在非东八区的设备上打开小程序直接从new Date()取本地时间会有偏差。微信小程序的new Date()已经换算成用户时区如果你要固定北京时间就得自己加补偿这一步要结合产品需求来定。场景 3时间戳以秒为单位如果你发现所有日期都显示在 1970 年附近那一定是秒级时间戳没有乘以 1000。这种情况我在线上见过不止一次原因是后端 Java 最常用毫秒PHP 最常用秒只要接口文档不明确前端就得自己兜底。场景 4字符串日期格式为null字符串这个很隐蔽。接口返回的字段被序列化成字符串null直接new Date(null)在 iOS 上会返回 Invalid Date页面就会显示空字符串。我的工具对null、undefined做了显式判断返回空值。场景 5格式化后中文环境出现星期错乱这个和日期解析无关但经常被误会在日期工具上。其实是getDay()返回 0-6需要自己映射成[日,一,二,三,四,五,六]。很多封装会漏掉这个我在工具里也补了一个week字段的映射。另外还有一点要注意微信小程序里setData的数据不要直接塞Date对象因为setData本质上做的是 JSON 序列化Date会被转成字符串。我遇到过页面数据里明明是个时间对象setData之后就变成 ISO 字符串后续再格式化就走进了字符串解析分支反而触发了 iOS 的 NaN 问题。正确的做法是先把日期格式化好再放进setData。4.3 扩展能力超越基础格式化这个工具只做基础格式化肯定不够我在不同项目里还经常给它加这些扩展功能相对时间描述已经写了fromNow日期范围组件支持比如开始时间、结束时间拼接中间加个~日历组件支持从一个月的 1 号到月末自动补全星期倒计时功能距离某个时间点还剩x天x小时x分x秒。倒计时这块有点意思微信小程序里经常用做限时活动。要注意的是倒计时不能频繁setData整个页面否则性能跟不上。我当时是在页面里用定时器每秒更新一次剩余时间字符串同时只更新一个 text 节点的值。如果你的页面比较重建议用selectComponent单独封装一个倒计时组件避免其他组件频繁刷新。顺带推荐一个组合思路定义全局过滤器函数在 WXML 里没法直接用函数调用一般是在 Page 的onLoad里把工具挂到this上或者通过WXS来格式化。WXS 是微信小程序特有的脚本语言对性能有帮助但语法受限不能直接复用我们写的util.js需要单独写一份 WXS 版本。如果你的项目列表页很多、一次性要渲染上百条日期尽量用 WXS 版本来格式化避免在主线程里做大量计算导致页面卡顿。关于 WXS 版本我简单给个思路代码大致如下// date.wxs function pad2(n) { return n 10 ? 0 n : n; } function formatDate(dateStr, fmt) { if (!dateStr) return ; var d getDate(dateStr.replace(/-/g, /)); if (!d) return ; var o { YYYY: d.getFullYear(), MM: pad2(d.getMonth() 1), DD: pad2(d.getDate()) }; return fmt.replace(/YYYY|MM|DD/g, function(match) { return o[match]; }); } module.exports { formatDate: formatDate };WXS 模块里用getDate而不是new Date这一点非常容易踩坑new Date在 WXS 里不存在。正则的支持也比普通 JS 弱一些编写时要注意语法兼容。列表数据在data里传给 WXML 前先经过这个formatDate渲染时不会再执行 JS 逻辑性能会好得多。我的经验是复杂工具函数放普通 JS简单格式化放 WXS两者分工明确。5. 工程化落地的一些心得5.1 代码组织与团队协作在项目里引入日期格式化工具最忌讳的是每个开发者各自 fork 一份去改。我在团队里推的是单一utils/date.js导出页面只调用formatDate、fromNow。如果后续要扩展时区策略只改这个文件但改动前一定要跑完测试用例。另外日期工具最好是纯函数不要依赖全局状态也不要直接修改传入参数。我在写normalizeDate时就特别注意这一点输入字符串不会被修改内部用新变量承接转换结果。这样即便未来有人把它放进 worker 线程跑也不会出问题。5.2 情绪价值与实际收益封装这个工具看起来是个很小的基建工作但收益是长期的。项目里所有日期展示都走同一套逻辑之后排查问题变得非常快——只要看到NaN立刻定位到输入日期字符串的格式不用再逐个页面去查。我个人习惯在项目根目录的docs/date-format.md里记录当前工具支持的所有模板字符和已知兼容问题比如 iOS-分隔符问题、WXS 不能使用new Date等。新同学入职看一遍文档就能上手不必等踩坑了才恍然大悟。最后再分享一个小技巧如果你在小程序里使用 TypeScript可以给formatDate加一个重载类型让传入的日期类型更加明确。这样在编译期就能拦截一部分非法传参比运行时报NaN再排查要高效得多。类型定义大致长这样type DateInput number | string | Date; function formatDate(date: DateInput, fmt?: string): string; function fromNow(date: DateInput): string;有了这层约束团队协作时接口风格也能更统一减少因为日期类型各写各的导致的混乱。日期处理这种基础能力越早规范化后期收益越大。