$ dateToString 的 timezone 参数仅对 BSON Date 类型生效，输入为字符串或毫秒数时会被静默忽略；须先用 $dateFromString 或 $toDate 转换为合法日期对象。
为什么 $dateToString 直接用时区参数会出错？
很多人一上来就写 { $dateToString: { date: "$ts", format: "%Y-%m-%d", timezone: "Asia/Shanghai" } }，发现结果不对——尤其当原始字段是字符串或毫秒数时，MongoDB 会静默忽略 timezone 参数，甚至返回空值。根本原因是：$dateToString 的 timezone 只对 BSON Date 类型生效，且必须确保输入已是合法日期对象。常见错误场景包括：字段存的是 ISO 字符串（如 "2024-05-20T12:00:00Z"）、时间戳数字、或带时区偏移但未标准化的字符串。
实操建议：
- 先用
$dateFromString显式转成 Date 对象，强制指定timezone或onError处理异常 - 若原始字段是 UTC 时间戳（毫秒数），直接用
$toDate转换，它会自动按 UTC 解析，再配合$dateToString的timezone做输出对齐 - 避免依赖驱动层做时区转换后再传入聚合，否则失去管道内统一时序对齐能力
如何让不同时区的事件在同一天维度归并统计？
比如要统计“全球用户在各自本地时间的 2024-05-20”发生的订单数，不能简单用 $dateToString 输出字符串再 $group——因为不同 timezone 下同一天起止时刻对应 UTC 时间段完全不同。正确做法是：把每个事件时间先转为对应时区的本地零点（start of day），再转回 UTC 时间戳用于分组。
实操建议：
- 用
$dateFromString+timezone将原始时间解析为该时区下的 Date 对象 - 用
$dateFromParts提取年/月/日，并显式传入同一timezone，生成该时区当天 00:00:00 的 Date - 用
$subtract计算原始时间与当日零点的时间差（毫秒），再加回零点时间，得到对齐后的标准时间点 - 最终用
$dateToString输出格式化字符串，或用$dateToParts提取结构化日期字段用于$group
$dateToParts 的 timezone 参数到底影响什么？
这个函数常被误认为只是“格式化工具”，其实它的 timezone 决定了年月日的拆解基准——不是简单加减偏移，而是按目标时区的日历规则计算。例如，UTC 时间 2024-05-20T18:00:00Z 在 "Asia/Tokyo"（UTC+9）下是 2024-05-21，而 $dateToParts 设 timezone: "Asia/Tokyo" 就会返回 { year: 2024, month: 5, day: 21 }；设成 "America/Los_Angeles"（UTC-7）则返回 day: 20。
实操建议：
- 需要按用户本地日历归档（如“5月21日订单”），就用用户所在时区调用
$dateToParts - 不要在
$dateToParts后再手动加减小时数来模拟时区，那会破坏夏令时等边界逻辑 - 注意 MongoDB 版本：4.0+ 才支持
timezone，4.4+ 才支持 IANA 时区名（如"Europe/Berlin"），旧版本只能用±HH:MM格式
聚合中动态时区字段怎么安全传入？
业务中时区往往存在文档里（如 user.timezone: "America/New_York"），但 $dateToString 和 $dateToParts 的 timezone 不接受变量表达式，直接写 timezone: "$timezone" 会报错 "timezone must be a string constant"。这是硬限制，无法绕过。
实操建议：
- 预定义有限时区集合，用
$switch+ 多个$branch分支分别处理常见时区（如"UTC","Asia/Shanghai","America/New_York"） - 若时区种类过多，改用应用层分批聚合：先
$group按timezone分桶，再对每组单独运行带固定时区参数的聚合 - 避免把时区字符串拼进
$dateFromString的format字段——那只会导致解析失败，不是时区转换
真正难的不是语法，是意识到 MongoDB 的时区支持是“静态声明式”的：你得提前知道有哪些时区要处理，而不是运行时任意切换。这点和应用层 Date API 完全不同，容易掉坑里。
