你是否遇到过这样的情况：使用 $dateDiff 计算分钟差时，结果始终为 0？这在实践中是一个极易踩坑的细节。根本原因在于，输入字段可能并非 Date 类型，而是字符串或数字。MongoDB 的 $dateDiff 不会自动执行类型转换，遇到非 Date 值会直接返回 null 或 0，且不抛出任何错误，排查起来相当耗费精力。
如何规避这一陷阱？从实战经验看，有几个关键步骤需要重点关注：首先利用 $type 确认字段类型，例如 {$expr: {$eq: [{$type: "$startAt"}, "date"]}}，这是最稳妥的前置校验。若发现字段为字符串，必须通过 $dateFromString 进行转换，不要指望隐式类型转换。此外，时区问题同样不容忽视：字符串解析默认采用 UTC 时区，如果原始数据包含本地时区偏移量（比如 "2024-05-20T14:30:00+08:00"），$dateFromString 能够正确解析；但若字符串不含偏移，则需显式指定 timezone 参数，否则容易导致计算结果偏差。
接下来，我们看一个使用 $dateDiff 计算分钟差的最小完整示例。核心要点是：必须显式指定 unit: "minute"，且两个日期字段都必须是正经的 Date 类型。下面是在聚合管道中计算 startAt 到 endAt 分钟差的代码：
{ $addFields: { durationMinutes: { $dateDiff: { startDate: "$startAt", endDate: "$endAt", unit: "minute" } } }}
这里有一些硬性约束：startDate 必须早于 endDate，否则返回负数（注意不是绝对值）。另外，无论字段格式看起来多标准，直接传入字符串都不行。如果字段可能为空或缺失，务必使用 $ifNull 保底，例如 startDate: {$ifNull: ["$startAt", "$$NOW"]}，避免整个表达式崩溃。
当数据存储为 "2024-05-20T09:15:22" 这类字符串时，不要尝试跳过转换步骤，建议采用带容错的三步安全转换方案：先用 $dateFromString 处理，并设置 onError 和 onNull 为 null，这样即使某条数据异常也不会导致整个聚合失败。转换失败后字段值为 null，$dateDiff 对 null 输入同样返回 null，下游再通过 $ifNull 统一兜底即可。需要特别注意的是，不要用 $toDate 替代 $dateFromString —— $toDate 对字符串的支持有限，且缺少 onError 控制，不够安全。
最后提醒一下性能与兼容性方面的要点。$dateDiff 是 MongoDB 5.0+ 引入的操作符，4.x 及更早版本无法使用。生产环境务必确认 MongoDB 版本。
在性能层面，$dateDiff 不能直接在 $match 阶段用于范围过滤，因为它无法利用索引。正确的做法是先用 $gte/$lte 粗筛时间范围，再在 $addFields 中精算分钟差。当处理大量文档的分钟级计算时，需留意聚合内存限制，可能需要启用 allowDiskUse: true。如果只需判断“是否超过 N 分钟”，用毫秒差加整除的方式更轻量：{$divide: [{$subtract: ["$endAt", "$startAt"]}, 60000]}，注意这种方式返回浮点数，且不处理类型错误。
一个极易被忽略的细节是：$dateDiff 的 unit: "minute" 采用向下取整（floor），而非四舍五入。例如 90.9 秒算作 1 分钟，119.9 秒仍为 1 分钟，只有 120 秒才会算作 2 分钟。这一特性在需要精确计时的场景中容易引发问题。
