日期时间格式化工具 - 自定义格式、ISO8601与多时区输出
🕘 同一刻,四种写法
后端接口里躺着 2026-10-25T00:00:00Z。运维在日志里看到的是 2026-10-25 08:00:00.412。导出报表时,文件名要求写成 report_20261025.csv。发给新加坡同事的表格里,那一列是 2026-10-25 08:00。
四个字符串,指向同一刻。谁都没算错,它们只是四种「呈现方式」。
日期时间格式化做的就是这件事:把「某一刻」写成「某一串字符」。听起来像是最没技术含量的操作——拼字符串而已——但线上事故里,格式造成的损失一点不比算错少:
- 接口字段的时区偏移写错,客户端显示的时间整体差八小时,日志和账单对不上;
- 日志格式一天一个样,正则切不出来,排查时只能肉眼翻;
- 文件名用
DDMMYYYY,按名字排序时 3 月 1 日排在 1 月 2 日前面; - 12 小时制漏了 AM/PM,下午三点的发布会通知写成凌晨三点。
星点的 日期时间格式化工具 处理的就是这一层:给定一个时间和它的来源时区,按预设或自定义模板输出字符串。来源时区与输出时区可以分开选,未知的 token 会明确提示而不是悄悄吞掉。全部在浏览器本地完成,输入不上传。
🧭 先确定这一刻,再决定怎么写
格式化工具不负责算时间,它负责「渲染」。所以它要两样东西:一个时间瞬间,一个用来呈现的时区。缺了后者,字符串就没有唯一含义。
2026-10-25 08:00:00 这串字符,本身只是钟表读数。它在 Asia/Shanghai 是 UTC 00:00,在 Europe/Berlin 是 UTC 06:00,差六小时。工具里「来源时区」这个选项,作用就是替你补上缺失的那一半信息:这个读数,是哪个时区的钟表显示的。
补完之后,瞬间就定住了。接下来才是「输出时区」——决定这个瞬间以哪个地方的当地时间写出来。
两个时区,两种职责
| 选项 | 回答的问题 | 选错的后果 |
|---|---|---|
| 来源时区 | 输入的这个读数,属于哪个时区? | 瞬间整体偏移,所有输出一起错 |
| 输出时区 | 结果要以哪个地方的当地时间显示? | 字符串里的钟表数字错,但瞬间没变 |
这两个概念最容易混在一起。很多人以为「改了输出时区就是把时间改一下」,其实改的是「同一刻在不同地方的钟表读数」,不是「时间本身」。
工具会把两个时区各自的偏移都显示出来,这一点很实用:一眼就能看出两边差几个小时、有没有踩到夏令时。
只改后缀不改时区,是最常见的错
举个具体的例子。你有一个 UTC 时间的字符串:
2026-10-25T00:00:00Z现在要求「用北京时间表示」。有人直接把 Z 换成 +08:00:
2026-10-25T00:00:00+08:00 ← 错这串字符语法完全合法,看着也像模像样,但它指向的是另一刻:+08:00 的 00:00,等于 UTC 前一天 16:00,比原来早了八小时。
正确做法是把瞬间保持不变,让钟表读数变:
2026-10-25T08:00:00+08:00 ← 对同一刻,UTC 是 0 点,北京是 8 点。
同样的错法还有几种变体:
- 给本地时间硬加
Z,2026-10-25 08:00:00Z变成了 UTC 早上八点,实际差了八小时; - 偏移写成
+8:00或-5,非标准的位数,严格的解析器会拒绝,宽松的会猜; - 时区选了
America/New_York,却把偏移手写成+08:00,字符串自相矛盾。
在工具里做对这件事很简单:输入时间、把来源时区选对、把输出时区选成目标地区,让工具去算偏移。手写偏移这件事,能不做就不做。
🔤 token 速查:大小写决定含义
自定义模板用的是 Day.js 风格的 token。这套写法在 JavaScript 生态里最常见,特点是大小写敏感,而且很多 token 只差一个字母就完全是另一个意思。
常用的一批:
| token | 含义 | 示例 |
|---|---|---|
YYYY | 四位年份 | 2026 |
YY | 两位年份 | 26 |
MM | 月份,补零(01–12) | 10 |
M | 月份,不补零 | 10 |
MMM | 月份英文缩写 | Oct |
MMMM | 月份英文全称 | October |
DD | 日期,补零(01–31) | 25 |
D | 日期,不补零 | 25 |
dddd | 星期全称 | Sunday |
HH | 小时,24 小时制,补零 | 08 |
H | 小时,24 小时制,不补零 | 8 |
hh | 小时,12 小时制,补零 | 08 |
h | 小时,12 小时制,不补零 | 8 |
mm | 分钟,补零 | 03 |
m | 分钟,不补零 | 3 |
ss | 秒,补零 | 07 |
s | 秒,不补零 | 7 |
SSS | 毫秒,三位 | 412 |
A | 上午/下午,大写 | AM |
a | 上午/下午,小写 | am |
Z | UTC 偏移,带冒号 | +08:00 |
ZZ | UTC 偏移,不带冒号 | +0800 |
具体支持哪些 token、有没有 X(Unix 秒)这类扩展写法,以工具页面内的速查表为准,不必凭记忆赌。
MM 是月,mm 是分
这是所有格式符体系里最经典的坑,几乎每个写时间的人都被它咬过一次。
MM= 月份(Month)mm= 分钟(minute)
写 2026-10-25 08:MM:00,得到的是 2026-10-25 08:10:00——分钟位置被塞进了月份。这种错很阴险:输出看起来依然是合法时间,只是数值错了,测试用例不覆盖就发现不了。
反过来写 YYYY-mm-DD 更糟,日期会变成 2026-10-25 里的月份被替换成分钟数,跨分钟边界时结果还会变。
HH 是 24 小时,hh 是 12 小时
HH= 24 小时制(00–23)hh= 12 小时制(01–12)
用 hh 必须配 A 或 a,否则上午八点和晚上八点都输出 08,字符串里没有任何信息能区分它们。这是最容易被忽略的半截格式:
hh:mm:ss → 08:00:00(早上还是晚上?不知道)hh:mm:ss A → 08:00:00 PM(这才是完整的)HH:mm:ss → 20:00:00(也完整)给机器读的字段一律用 HH。需要 12 小时制的场合基本只有一个:给人看的界面,而且用户习惯那种写法。
其他几组容易混的
DD是日,dddd是星期几的全称,ddd是缩写(Sun)。写成dd会拿到星期缩写而不是日期。MMM是Oct,MM是10。想要10月这种中文,别指望 token 翻译,直接写中文加 token:M月D日。YY只有两位,跨世纪时会歧义。存数据、写文件名的场合坚持用YYYY。SSS是毫秒三位。来源数据是微秒(六位)时,这里会被截断,不是四舍五入。
📋 预设格式:先想想这串字符串给谁看
工具内置了一批预设,覆盖大部分日常场景。选预设比自己拼模板更稳,因为它已经处理好补零和偏移。
| 预设 | 典型输出 | 适合用在 | 注意 |
|---|---|---|---|
| ISO 8601 / RFC 3339 | 2026-10-25T00:00:00Z | 接口字段、配置文件、跨系统传输 | 带偏移,瞬间唯一,机器友好 |
YYYY-MM-DD HH:mm:ss | 2026-10-25 08:00:00 | 数据库、Excel、工单、聊天 | 不带偏移,必须另行说明时区 |
| 斜杠 / 中文日期 | 2026/10/25、2026年10月25日 | 报表抬头、合同、给非技术同事看 | 排序不可靠,别用于文件名 |
| 仅日期 | 2026-10-25 | 按天聚合、日历、有效期 | 丢了时分秒,跨时区时日期可能不同 |
| 仅时间 | 08:00:00 | 营业时间、排班、班次表 | 必须配合日期和时区才有意义 |
| UTC | 2026-10-25 00:00:00Z 一类 | 日志、审计、对账 | 与「本地时间」是两个东西 |
| Unix 秒 / 毫秒 | 1792886400 / 1792886400000 | 数据库字段、缓存 key、过期时间 | 纯数字,与时区无关 |
有一件事值得单独说:选 Unix 时间戳作为输出时,切换输出时区不会改变结果。因为时间戳记录的是「距 1970-01-01 00:00:00 UTC 多少秒」,它本来就不带时区。这时「输出时区」只影响输入时间的解释,不影响输出的那个数字。有人看到数字没变,以为工具没生效,其实是这个格式天然与时区无关。
ISO 8601 和 RFC 3339 不是一回事
接口文档里写「用 ISO 8601 格式」,这句话其实不够精确。
ISO 8601 是一个很大的家族,涵盖日期、时间、时长、周历、序数日期等各种写法,而且允许省略偏移。2026-10-25T08:00:00 是合法的 ISO 8601,但它没告诉你这是哪个时区的时间,不指向唯一瞬间。
RFC 3339 是它的一个严格子集,专门为互联网协议设计:用 T 分隔日期和时间,必须带偏移(Z 或 +08:00),小数秒可选。这才是接口里真正想要的东西。
所以看到「ISO 8601 格式」时,实际要问的是:带不带时区、带不带毫秒。两个问题的答案定了,格式才能定。
🚀 五步做完一次格式化
- 打开 日期时间格式化工具,在输入区填入或选择要处理的日期时间;
- 选来源时区——这个读数是谁的钟表。如果输入的字符串本身带了偏移(
2026-10-25T00:00:00Z),瞬间已经定住,但仍然建议核对一遍,别出现「字符串写 Z、界面选北京」这种自相矛盾的输入; - 选输出时区,默认与来源相同。要给海外同事看就换成对方所在时区,要写进接口就选 UTC;
- 选一个预设;预设不够用就切到「自定义」,填模板,比如
YYYYMMDD-HHmmss; - 结果区实时刷新,逐项复制。
复制之前有三个习惯值得养成:
- 往接口里贴的,先确认结尾是
Z还是+08:00,别把本地时间当 UTC 发出去; - 写进文件名的,先看一遍有没有冒号(Windows 文件名不允许),
HH:mm:ss要换成HHmmss; - 需要给同事核对时,把结果再贴回 时间戳转换工具 看一眼它对应的 UTC 和 Unix 秒,两边对得上,说明时区没选错。
自定义模板里如果写了工具不认识的 token,结果区会给出提示,而不是输出一串看着正常其实错位的字符。这个行为比「静默容错」有用得多——格式化的错,最怕的就是不报错。
🧪 三个完整例子
例一:把业务时间写成 RFC 3339 给接口
场景:活动在北京时间 2026 年 10 月 25 日上午 8 点开始,接口要求 RFC 3339。
输入 2026-10-25 08:00:00,来源时区 Asia/Shanghai,输出时区 UTC,选 ISO 8601 / RFC 3339 预设:
2026-10-25T00:00:00Z如果后端要求保存带偏移的写法,把输出时区改成 Asia/Shanghai:
2026-10-25T08:00:00+08:00两种写法指向同一刻,Unix 秒都是 1792886400,选哪种只看对方接口的约定。
例二:给导出文件起一个能排序的名字
场景:每天导一次报表,文件名要能按时间排。
模板 report_YYYYMMDD-HHmmss.csv,输出 report_20261025-080307.csv。
为什么坚持「年在前」:按字符串排序时,20261025 和 20261101 的顺序和实际时间一致;换成 25102026 这种日月年写法,排序立刻乱掉,归档目录里一眼看不出哪份最新。这是文件命名的老规矩,但每年还是有人踩。
顺带一句:文件名里不要出现 :,Windows 会直接拒绝;也不要用 /,会被当路径分隔符。
例三:写一条固定宽度的日志时间
场景:日志要求 YYYY-MM-DD HH:mm:ss.SSS,且必须带毫秒。
来源 2026-10-25 08:00:00.412(Asia/Shanghai),输出时区保持 Asia/Shanghai:
2026-10-25 08:00:00.412同一刻换成纽约(America/New_York,当天是夏令时 −04:00):
2026-10-24 20:00:00.412日期退了一天。这就是为什么日志时间必须带时区或统一用 UTC——同一个 .412,在不同地区的日志里日期都不一样,只靠肉眼比对根本对不上。
🐛 七个高频错误
1. Java 的 yyyy / YYYY、dd / DD 混着用
Java 的 SimpleDateFormat 和 DateTimeFormatter 里,大小写含义完全不同:
yyyy是日历年,YYYY是周所属年(week-based year);dd是月内日期,DD是年内第几天。
后果不是差一点,是整段错位。2021-01-01 用 YYYY-MM-dd 格式化,因为那天属于 2020 年的最后一周,输出变成 2020-01-01;2021-12-31 用 yyyy-MM-DD,输出变成 2021-12-365。
这类 bug 只在每年头尾几天出现,测试年年过,除夕那天上线就炸。本工具用的是 Day.js 风格 token,YYYY 就是日历年、DD 就是日期,不存在周所属年的问题;反过来说,从 Java 代码里抄模板过来时,别直接抄。
2. 把 Python 的 strftime 写进模板
Python 的写法是 %Y-%m-%d %H:%M:%S。把这一串直接贴进自定义模板,% 会被当字面量,后面的 Y、d、H 这些单字母又不是合法 token,结果要么报错,要么输出一堆奇怪字符。
三个体系的对照放在一起看,才不会抄错:
| 目标 | Day.js 风格 | Java | Python strftime |
|---|---|---|---|
| 四位年 | YYYY | yyyy | %Y |
| 月(两位) | MM | MM | %m |
| 日(两位) | DD | dd | %d |
| 时(24 小时) | HH | HH | %H |
| 分 | mm | mm | %M |
| 秒 | ss | ss | %S |
| 毫秒 | SSS | SSS | %f(微秒,六位) |
注意 Python 那一列:%M 是分钟,%m 是月份,又是一组只差大小写的。而 %f 是六位微秒,不是三位毫秒,直接对应会多出三位数字。
3. 未知 token 被静默吞掉
这是「看起来成功、其实错了」的典型。模板里写 QQ、yyyy(小写)、%Y,一个宽松的实现可能把不认识的字符原样输出,也可能直接丢掉不报错。
结果就是这样:模板 yyyy-MM-dd,输出 yyyy-10-25,或者输出 -10-25。前者一眼能看出不对,后者要盯两秒才发现日期少了。
用工具时,遇到不认识的 token 会有明确提示,照着页面里的速查表改就行。自己也该有个意识:模板写完之后,先看一遍输出是不是符合作者预期,别只看「有没有结果」。
顺带一个细节:中文、标点、空格这些非字母字符会被当字面量原样输出,所以 YYYY年MM月DD日 是能直接用的。但英文字母组合要小心,at、on、T 这类在模板里可能被拆成 token——想做分隔符,优先用中文、空格、标点,或者用工具支持的转义写法(以页面说明为准)。
4. 大小写随手写
MM 和 mm、HH 和 hh、DD 和 dd,前面已经说过。这里补一个角度:这三个坑的共同点是错误输出的语法合法性。它们不会让程序崩溃,只会让数据静静地错。所以格式模板这种东西,写完必须拿一个「月份和分钟明显不同、上午下午都有」的时间点验证一次,比如 2026-10-25 20:03:00:分钟 03 和月份 10 不同,晚上八点用 hh 会显示 08。一次验证能抓出大部分错误。
5. 偏移写错或写得不规范
+08:00 是标准写法。+8:00、+0800(在要求冒号的场合)、-5、UTC+8 这些写法,不同解析器的宽容度不一样,跨系统传输时最好统一成 ±HH:MM。
更麻烦的是偏移和时区不匹配:输出时区选的是纽约,字符串后缀却写 +08:00。这种字符串自相矛盾,有的库以偏移为准,有的以时区为准,结果取决于实现——排查起来能耗掉半天。
还有一类:把「本地时间 + 正确的偏移」当成「UTC 时间」。2026-10-25T08:00:00+08:00 和 2026-10-25T08:00:00Z 差八小时,前者是北京时间早上八点,后者是 UTC 早上八点(北京下午四点)。两者只差一个字符。
6. 把 Unix 时间戳当成格式模板
1792886400 这串数字,有人会直接贴进自定义模板框,以为工具会「把它格式化」。实际上模板框要的是格式描述,不是数据。数字会被原样输出,看起来像成功了,其实什么都没做。
正确的路径是:先把时间戳放进 时间戳转换工具,把它换成日期时间(或反向),再拿这个时间去做格式化。两个工具的职责不同,别混着用。
还有一种「反向混淆」也常见:以为格式化能把秒变成毫秒。它不会。秒与毫秒差三个数量级,要用 时间戳转换工具 的单位换算,或者在模板里用 SSS 把毫秒位写出来——但那是把「毫秒部分」显示出来,不是把秒数乘以 1000。
7. 拿「我的本地时间」当「大家的本地时间」
浏览器里的「本地时区」是设备的时区,不是用户真实所在地。出差没改系统时区、公司电脑统一锁了时区、用 VPN 改了区域,都会让默认输出偏掉。
更常见的是团队协作:A 在自己机器上格式化成 2026-10-25 08:00 发给 B,B 的机器在纽约,他看到的这串字符会被理解成纽约时间。字符串里没有时区,靠聊天记录补不回来。
处理办法很朴素:跨人、跨系统传输的字符串,要么带偏移,要么明确约定 UTC。只给本地钟表读数的,都算没写完。
🧰 和相邻工具的分工
时间类工具容易混用,其实各自的输入输出很清晰:
| 工具 | 方向 | 输入 → 输出 |
|---|---|---|
| 日期时间格式化 | 瞬间 → 字符串 | 一个时间 + 模板 → 格式化后的文本 |
| 时间戳转换 | 瞬间 ↔ 数字 | 时间戳 ⇄ 日期时间,秒/毫秒互转 |
| 时区转换 | 一瞬间 → 多时区 | 同一刻在各 IANA 时区的对照表 |
| 时间字符串解析 | 字符串 → 瞬间 | 识别格式、暴露歧义、拆成字段 |
顺序上通常是这样:拿到一个不确定的时间字符串,先解析确认它是哪一刻;需要看它在各地的时间,用时区转换;需要输出成某种格式给系统或人,用格式化;需要和数据库里的数字对账,用时间戳转换。
格式化工具不判断「这个字符串是什么意思」,它默认你已经知道输入代表哪一刻。这个前提不成立的时候,先去解析,别硬格式化。
📌 一份可以贴在显示器上的清单
- 机器读的字段用 RFC 3339,带偏移,别省
Z; - 人看的界面可以用本地格式,但旁边标注时区;
- 文件名用
YYYYMMDD,别用日月年,别带冒号; - 日志统一 UTC,格式固定宽度,毫秒位保留;
- 12 小时制必须带 AM/PM,否则一律 24 小时制;
- 模板写完,用
2026-10-25 20:03:00这种时间点验一遍; - 跨人传输的字符串,没有偏移就等于没写完。
❓ 常见问题
MM 和 mm 到底哪个是月?
MM 是月份(Month),mm 是分钟(minute)。同理 HH 是 24 小时制,hh 是 12 小时制,DD 是日期,dd 是星期缩写。这套 token 大小写敏感,写反了不会报错,只会输出一个看起来正常但内容错误的时间。
为什么模板里写 yyyy-MM-dd 会报错?
因为本工具用 Day.js 风格 token,四位年要写YYYY,小写 yyyy 不是合法 token(那是 Java 的写法)。遇到这类提示,照着页面内的 token 速查表改大小写即可。YYYY-MM-DD 才是正确的写法。
换了输出时区,为什么 Unix 时间戳没变?
因为 Unix 时间戳记录的是「距 1970-01-01 00:00:00 UTC 的秒数」,它本身不带时区,也不受显示时区影响。输出时区只改变「钟表读数」这一类格式的结果。同一刻在北京和纽约的时间戳完全相同,这正是它适合做存储和比较的原因。ISO 8601 和 RFC 3339 该用哪个?
给接口、配置文件、跨系统传输,用 RFC 3339:它要求带偏移(Z 或 +08:00),瞬间唯一。ISO 8601 是更大的家族,允许省略偏移,省略之后就不指向唯一瞬间,只适合人读或本地场景。接口文档写「ISO 8601」时,最好追问一句「带不带时区、带不带毫秒」。
毫秒只有三位,我的数据是微秒怎么办?
SSS 输出三位毫秒,微秒的后三位会被截掉,不是四舍五入。如果精度确实要到微秒,这个格式表达不了,得在数据层单独保留;大多数业务场景(日志排序、接口时间戳)毫秒已经够用。
为什么用 hh 的时候上午下午显示一样?
因为hh 只输出 12 小时制的钟表数字,早上八点和晚上八点都是 08,没有 AM/PM 就无法区分。要么补上 A(hh:mm A),要么直接用 24 小时制的 HH。给程序读的字段建议一律用 HH。
工具会把我的时间数据上传吗?需要登录吗?
不会,也不需要登录。所有格式化都在浏览器本地完成,不产生网络请求,输入的时间不上传。处理内部日志、接口返回值、还没公布的排期都可以放心用。🔗 相关工具
💬 收尾
格式化的难点从来不是拼字符串,而是想清楚两件事:这串字符代表哪一刻,以及它要给谁看。
前者靠时区定住,后者靠格式表达。这两件事分开处理,接口不会再差八小时,文件也能按时间排好,日志能被正则切开。反过来,把这两件事混在一起——改后缀当改时区、拿本地时间当 UTC、模板抄错列——错误都会以「看起来正常」的样子混进数据里,等到对账那天才暴露。
下次写完模板,拿 2026-10-25 20:03:00 跑一遍。月份是 10、分钟是 03、晚上八点在 24 小时制里是 20,三个数字都不一样,错了立刻能看出来。
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!