本文详解为何 differenceInCalendarDays 返回 NaN，并演示如何通过 parseISO 将字符串日期安全转换为 Date 对象，从而准确获取日历天数差。
本文详解为何 `differenceincalendardays` 返回 nan，并演示如何通过 `parseiso` 将字符串日期安全转换为 date 对象，从而准确获取日历天数差。
在使用 date-fns 的 differenceInCalendarDays 计算日期差时，一个常见误区是直接传入格式化后的字符串（如 "2024-05-10T14:30:00" 或本地化格式文本），而非有效的 Date 实例。该函数严格要求参数为 Date 类型；若传入字符串、null、undefined 或无效日期，将返回 NaN —— 这正是你遇到问题的根本原因。
differenceInCalendarDays 不解析日期字符串，它只做纯日期对象间的日历日差计算（即忽略时间部分，仅比较年/月/日）。因此，必须先将输入字符串显式解析为 Date 对象。推荐使用 parseISO（适用于 ISO 8601 格式，如 "2024-03-15" 或 "2024-03-15T08:00:00Z"），它是 date-fns 中轻量、可靠且无副作用的解析工具：
import { differenceInCalendarDays, parseISO } from "date-fns";
export function getDifferenceDate(startDate: string, endDate: string): number {
const start = parseISO(startDate); // ✅ 安全转换为 Date
const end = parseISO(endDate); // ✅ 同上
// 建议添加基础校验，提升健壮性
if (isNaN(start.getTime()) || isNaN(end.getTime())) {
throw new Error("Invalid date string provided. Expected ISO 8601 format (e.g., '2024-03-15').");
}
return differenceInCalendarDays(start, end);
}
// 使用示例：
console.log(getDifferenceDate("2024-03-10", "2024-03-15")); // → 5
console.log(getDifferenceDate("2024-01-01", "2023-12-25")); // → -7（负值表示 endDate 更早）⚠️ 注意事项：
- ❌ 不要传入
format()生成的本地化字符串（如getCurrentDate()返回的"10 мая 2024 г., 14:30"），parseISO无法识别； - ✅ 确保输入字符串符合 ISO 格式（
YYYY-MM-DD或YYYY-MM-DDTHH:mm:ss.sssZ）； - ? 若需处理其他格式（如
"DD.MM.YYYY"），应改用parse并指定locale和pattern，而非parseISO； - ?
differenceInCalendarDays返回的是整数天数差（向下取整到日），不考虑时分秒——这与differenceInDays（基于毫秒差四舍五入）不同，请按业务需求选择。
总结：日期计算前必先解析。parseISO 是处理标准时间字符串的首选，配合类型检查与错误提示，可彻底避免 NaN 陷阱，让日期逻辑稳定、可维护、易测试。
