$dateAdd（日期加法）
最后更新：2026-10-09
$dateAdd（日期加法）
$dateAdd 在指定日期上增加一定数量的时间单位，返回新的日期，是聚合管道中计算相对日期（如到期日、续费日、截止时间）的首选操作符。unit 支持 year、month、week、day、hour、minute、second、millisecond 八种单位；amount 可为负数，等价于做减法。配合 timezone 可让计算基于指定时区的日历，处理跨月、跨年更准确。它可在 $project、$addFields、$set 等阶段使用，也可嵌套进其他表达式。
| 分类 | 日期 |
|---|---|
| MongoDB 版本 | 5.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $dateAdd: { startDate: <日期表达式>, unit: <时间单位>, amount: <数值>, timezone: <时区> } }⚙️ 参数
| startDate | 要修改的日期，可为 Date、时间戳或可解析为日期的表达式。 |
|---|---|
| unit | 时间单位：year、month、week、day、hour、minute、second、millisecond。 |
| amount | 增加的数量，正数加、负数减；超出 64 位整数范围会报错。 |
| timezone | 可选，计算基于的时区，支持 IANA 名（如 Asia/Shanghai）或 UTC 偏移。 |
返回值：增加后的新日期（BSON Date）；startDate 为 null 或缺失时返回 null。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $dateAdd：订单创建 30 天后为到期日（按北京时间）
db.orders.aggregate([
{ $project: {
dueDate: { $dateAdd: { startDate: '$createdAt', unit: 'day', amount: 30, timezone: 'Asia/Shanghai' } }
} }
])运行结果：
{ "_id": 1, "dueDate": ISODate("2026-10-25T00:00:00Z") }
{ "_id": 2, "dueDate": ISODate("2026-11-15T00:00:00Z") }📌 注意事项
- unit 只有上述 8 种；amount 超出 int64 范围会报错
- startDate 为 null 或缺失时返回 null，可配合 $ifNull 兜底
- 按月份加时以结果月的天数截断，例如 1 月 31 日加 1 个月得到 2 月最后一天
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q$dateAdd 一次能加几个单位？
A一次只能指定一个单位；需要多种单位时嵌套调用，或分多次 $dateAdd。
Qamount 支持负数吗？
A支持，负数等价于做减法，也可改用 $dateSubtract。
Q时区怎么指定？
A用 Asia/Shanghai 这类 IANA 名或 +08:00 偏移，缺省为 UTC。
