date-fns

date-fns

将此技能用于 date-fns v4 日期计算、格式化、解析、FP 模式、本地化，以及官方时区包 @date-fns/tz / @date-fns/utc。

工作流

1. 修改代码前，先检查本地环境：
   • 包：date-fns、可选的 @date-fns/tz、@date-fns/utc（以及存在时的旧版 date-fns-tz）。
   • 版本：优先使用 date-fns ≥ 4，以获得一流的 { in } / TZDate / UTCDate 互操作支持。v3 很常见，但仅适用于本地场景，除非使用 date-fns-tz。
   • 时区意图：系统本地 UI、规范化为 UTC 的服务端计算，或命名的 IANA 时区（用户/场馆/总部）。
   • 导入：从 "date-fns"、"date-fns/fp"、"date-fns/locale/*"、"date-fns/constants" 使用具名导入。
2. 版本不明确，或工作涉及时区、Unicode 标记、SSR 或重大升级时，更新文档。从 source-map.md 开始。
3. 按需查阅更深入的内容：
   • 安装、导入、核心概念、Invalid Date：setup-core.md。
   • format / parse / parseISO、Unicode 标记：format-parse.md。
   • 加减/设置/边界、差值、Interval、Duration：manipulate-compare.md。
   • TZDate、UTCDate、tz / utc、transpose、DST、SSR：timezones.md。
   • FP、本地化、TypeScript：fp-locales-types.md。
   • v2→v3→v4 和 date-fns-tz 迁移：migration-pitfalls.md。
4. 与项目已安装的主版本和现有导入风格保持一致。除非时区语义有此需要，否则不要添加 @date-fns/tz 或 @date-fns/utc。
5. 使用类型检查和针对性测试进行验证；相关时，测试 Invalid Date、日历差值与经过时间差值，以及时区/SSR 边缘情况。

时区决策树

System-local calendar / host TZ only?
  → plain Date + date-fns

UTC-only math (server day, charts, no IANA zones)?
  → @date-fns/utc (UTCDate / UTCDateMini or { in: utc })

Named IANA zone or multi-zone product?
  → @date-fns/tz (TZDate / TZDateMini or { in: tz("…") })

Stuck on date-fns v3?
  → upgrade to v4 + official packages, or use legacy date-fns-tz until then

核心判断

• 裸用 date-fns 时采用系统本地时区，它不是 UTC 库。对于非本地日历字段，请使用 @date-fns/utc 或 @date-fns/tz。
• 优先使用具名导入。常量从 "date-fns/constants" 导入，而不是从主导出入口导入。
• 始终先执行 isValid，再执行 format——format 遇到 Invalid Date 时会抛出 RangeError。
• Unicode 标记：使用 yyyy-MM-dd，不要使用 Moment 风格的 YYYY-MM-DD / DD（周历年 / 年中的第几天）。参见 format-parse.md。
• parseISO("YYYY-MM-DD") → 本地午夜；new Date("YYYY-MM-DD") → UTC 午夜。不要混为一谈。
• 日历日数相关问题优先使用 differenceInCalendar*；计算完整经过时间单位时使用 differenceIn*。
• 对于混合时区或原始值，使用 { in: tz("…") } 或 { in: utc } 固定上下文——否则，第一个对象 Date/扩展类型参数会决定时区，且参数顺序可能改变日期计算结果。
• new TZDate(iso, zone) ≠ 旧版 toZonedTime。它们表示同一时刻，但墙上时钟时间不同。墙上时钟映射使用 transpose。
• 在库边界处优先使用完整的 TZDate / UTCDate；Mini 变体会跳过支持时区的 toString / 本地化格式化器（可能泄漏系统时区）。
• 不要将 @date-fns/tz 与第三方 date-fns-tz 混淆。

验证

优先使用仓库自有命令。根据相关性覆盖以下项目：

• bun pm ls date-fns @date-fns/tz @date-fns/utc（迁移时也检查 date-fns-tz）。
• 针对 DateArg、选项类型和扩展类型返回值进行类型检查。
• 测试：有效/无效解析、Unicode 标记、日历差值与经过时间差值、反向区间、DST 春季向前/秋季向后切换、{ in } 与参数顺序的时区选择。
• 如果要格式化“今天”或本地日界线，且服务端（通常为 UTC）与客户端（本地时区）不一致，则进行 SSR/水合冒烟测试。

报告已运行和未运行的检查，以及仍然存在的版本假设。