原生Date对象设计反直觉，存在月份从0开始、字符串解析跨浏览器不一致、setMonth溢出、时区控制难四大经典坑；Moment.js功能全但已停更；date-fns轻量函数式为现代首选；Intl可满足简单格式化与国际化展示。
JavaScript原生的Date对象设计得不够直观，很多行为反直觉——比如月份从0开始、时区处理模糊、解析字符串依赖浏览器实现、跨浏览器不一致。这不是你写错了，是它本来就这么难。
原生Date的几个经典坑
月份从0开始：new Date(2023, 0, 1) 是2023年1月1日，但 new Date(2023, 1, 1) 是2月1日，不是1月——很多人传参时直接用“1”代表一月，结果错了一个月。
字符串解析靠猜：new Date('2023-01-01') 在Chrome里是UTC时间，但在Safari里可能被当作本地时间；'01/01/2023' 在美国解析为1月1日，在欧洲可能报错或误判。
setMonth()会溢出：对1月31日调用 setMonth(1)（想设成2月），结果变成3月3日——因为2月没有31号，它自动进位了，而且不报错。
立即学习“Java免费学习笔记（深入）”；
时区切换难控制：toISOString()强制转UTC，toString()用本地时区，toLocaleString()又受用户系统设置影响，想统一显示一个固定时区的时间，得手动算偏移量。
Moment.js：功能全但已进入维护模式
Moment.js曾是事实标准，API流畅，链式调用顺手，支持国际化和相对时间（如“2天前”）。但它体积大（约70KB压缩后）、不可变性弱（默认修改原对象）、且官方在2020年宣布进入维护模式，不再新增特性。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
如果项目已重度使用，可以继续用，但新项目不建议引入：
- 创建日期：moment('2023-01-01', 'YYYY-MM-DD')
- 格式化：moment().format('YYYY-MM-DD HH:mm')
- 加减：moment().add(3, 'days').subtract(1, 'month')
- 注意：.startOf('day') 和 .endOf('month') 很实用，但记得调用 .toDate() 才能得到原生Date对象
date-fns：轻量、函数式、现代首选
date-fns基于纯函数设计，每个API只做一件事，不修改原始日期（immutable），Tree-shaking友好（用多少引多少），体积小（单个函数通常不到1KB），且持续积极维护。
常用操作示例（v3+语法）：
- 解析字符串：parse('2023-01-01', 'yyyy-MM-dd', new Date())
- 格式化：format(new Date(), 'yyyy-MM-dd HH:mm:ss')
- 加减天数：addDays(new Date(), 5)
- 月初/月末：startOfMonth(new Date()) / endOfWeek(new Date(), { weekStartsOn: 1 })
- 比较：isBefore(date1, date2)、isSameDay(date1, date2)
它不内置i18n，但配合date-fns/locale可轻松切换语言，比如中文星期、农历格式需额外处理——这点反而让职责更清晰。
现代替代方案：Intl.DateTimeFormat + 原生Date（适合简单场景）
如果你只是格式化、本地化显示，不用复杂计算，原生+Intl已经足够强大且零依赖：
- new Intl.DateTimeFormat('zh-CN', { dateStyle: 'medium', timeStyle: 'short' }).format(new Date()) → “2023年1月1日 上午12:00”
- 时区可控：new Intl.DateTimeFormat('en-US', { timeZone: 'Asia/Shanghai' })
- 相对时间（实验性）：Intl.RelativeTimeFormat('zh-CN').format(-2, 'day') → “2天前”
缺点是不能直接做日期运算，但对展示类需求又快又稳。
基本上就这些。选date-fns覆盖90%业务场景，用Intl搞定国际化展示，避开Moment.js的新项目陷阱——日期处理不会变简单，但工具选对，至少少踩一半坑。
