$ dateToString 的 timezone 参数必须为严格 ISO 8601 偏移格式（如 "+08:00"），不支持 "Asia/Shanghai"；null、空字符串或非法格式会导致返回 null；需确保查询时间范围与聚合时区对齐，避免跨日统计错误。
聚合中 $dateToString 的 timezone 参数怎么填才有效
直接填 "+08:00" 或 "Asia/Shanghai" 都可能失败——MongoDB 原生只认 ISO 8601 时区偏移格式（如 "+08:00"），不支持 IANA 时区名（如 "Asia/Shanghai"），除非你用的是 MongoDB 5.0+ 且启用了 $convert + timezone 扩展，但绝大多数生产环境仍跑在 4.4 或 5.0 默认配置下。
-
timezone必须是字符串，且格式严格为±HH:mm（例如"+08:00"、"-05:00"），不能省略前导零，"+8:00"会报错 - 空值或非法值（如
null、""、"UTC"）会导致整个字段返回null，而不是回退到 UTC - 如果文档里
createdAt是null或非 Date 类型，$dateToString也会静默返回null，建议先用$type过滤或$cond容错
正确写法示例：
db.orders.aggregate([
{
$project: {
day: {
$dateToString: {
format: "%Y-%m-%d",
date: "$createdAt",
timezone: "+08:00"
}
}
}
},
{ $group: { _id: "$day", count: { $sum: 1 } } }
])
按天分组统计时，为什么查出来的“今天”总是少/多一天
根本原因不是聚合写错了，而是查询条件和分组逻辑的时区没对齐：你用 timezone: "+08:00" 在聚合里转了本地日，但 $group 本身不感知时区，它只是按字符串分组；而如果你上游没过滤好时间范围，UTC 存储的凌晨 0–7 点（对应北京时间早 8 点前）就会被算进“昨天”的字符串里。
- 典型陷阱：用
{ createdAt: { $gte: ISODate("2026-03-10T00:00:00Z") } }查“今天”，结果把北京时间 3 月 10 日 00:00–07:59 的数据漏掉了（它们在 UTC 是 3 月 9 日） - 正确做法是：先用 UTC 时间范围查出完整数据集，再在聚合里统一转本地日——别指望靠
$dateToString把乱序数据“拉回来” - 若要严格按北京时间当天统计，查询条件必须覆盖 UTC 的前一日 16:00 到当日 16:00（即
"2026-03-09T16:00:00Z"至"2026-03-10T16:00:00Z"）
Java/Spring Boot 里用 MongoTemplate 聚合，timezone 参数传不进去怎么办
MongoTemplate 的 Aggregation.project() 不直接暴露 timezone 字段，底层 BSON 构造器默认忽略该键——这不是 bug，是驱动版本兼容性问题。4.x 驱动基本不支持，5.0+ 需手动构造 Document。
- 低版本（如 spring-boot-starter-data-mongodb 3.4.x / driver 4.7.x）：只能绕过，用
$add+$multiply手动加 8 小时毫秒数再$dateToString - 推荐方案：改用原生
Document写聚合阶段，显式传timezone - 示例（Java）：
Document dateStr = new Document("format", "%Y-%m-%d")
.append("date", "$createdAt")
.append("timezone", "+08:00");
Document project = new Document("$project",
new Document("day", new Document("$dateToString", dateStr)));
为什么 Robo 3T / Compass 显示时间正常，但聚合结果还是错
工具显示的是“本地渲染”，和数据库存储无关。Robo 3T 的 Display Date In → Local Timezone 只改 UI 层解读方式，不影响任何查询或聚合逻辑——它甚至不会修改你发出去的命令里的 ISODate 值。
- 你在 shell 里敲
ISODate("2026-03-10T00:00:00Z")，工具显示成 “2026-03-10 08:00:00”，这只是视觉映射，实际传给服务端的仍是 UTC 字符串 - 聚合中所有时间运算（
$gt、$dateFromString、$hour等）都基于原始 UTC 值，UI 怎么显示完全不影响结果 - 调试时务必用
db.collection.findOne()看原始ISODate字段值，别信右侧面板的时间显示
最容易被忽略的一点：时区转换不是单次动作，而是贯穿写入、查询、聚合、展示四个环节的链路。任何一个环节漏掉 UTC 对齐，都会让“按天统计”变成玄学。
