时间戳转换避坑指南：时区、单位与跨端一致性

时间问题为什么总在上线后爆雷

时间戳问题最麻烦的地方在于：开发环境看着没问题，上线后才暴露。

典型原因：

• 秒级与毫秒级单位混用。
• 客户端与服务端时区不一致。
• 格式化规则在不同端不统一。

时间处理如果不统一规范，排查成本会非常高。

最常见的三个坑

1）10 位和 13 位混淆

10 位通常是秒，13 位通常是毫秒。误用会导致日期偏移几十年。

建议在数据入口做长度与范围校验，避免错误扩散。

2）本地时间与 UTC 混用

日志写本地时间，接口传 UTC，页面按用户时区展示——只要任一环节没说明，结果就会错。

3）格式字符串不一致

不同语言、不同库的格式化语法不完全一致，迁移时尤其容易出错。

一个稳定的时间处理策略

推荐团队统一原则：

• 存储层统一 UTC。
• 传输层统一时间戳或 ISO 标准。
• 展示层按用户时区格式化。

“存储一致、展示灵活”是跨端协作的最优解。

联调排错流程（可直接套用）

1. 确认原始时间值与单位。
2. 确认服务端时区配置。
3. 确认前端解析与格式化策略。
4. 用同一条样本在多端对照验证。
5. 记录结论并沉淀到接口文档。

标准流程能把排查从“猜测”变成“验证”。

业务场景建议

• 订单与支付：优先使用服务端时间，避免客户端时间漂移。
• 统计报表：明确自然日以哪个时区定义。
• 用户通知：展示层尽量使用本地化时间表达。

不同场景的“正确时间”定义并不相同。

结语

时间戳问题不是技术细节，而是系统设计问题。

只要你统一单位、时区与格式规范，绝大多数线上时间 bug 都可以提前避免。

相关工具入口

• 立即使用：/tools/timestamp
• 典型场景：联调时先确认输入是 10 位还是 13 位，再在工具中做双向转换并与后端样本对照。

若你需要把时间校验规则写进调试脚本，可配合正则测试工具：/tools/regex-test。