> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL 日期和时间函数

> MySQL 日期和时间函数参考指南：NOW、CURDATE、DATE_FORMAT、DATEDIFF、DATE_ADD、EXTRACT、STR_TO_DATE、UNIX_TIMESTAMP，以及常见的日期处理模式。

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

MySQL 提供了一整套日期和时间函数。您主要会用到的类型有 `DATE`（仅日期）、`TIME`（仅时间）、`DATETIME`（日期 + 时间，无时区）和 `TIMESTAMP`（日期 + 时间，以 UTC 存储，以会话时区显示）。有关时区处理的详细信息，请参阅 [MySQL 中的时间戳与时区](https://villagesql.com/docs/zh/guides/timestamps-timezones.md)。

## 获取当前日期和时间

```sql theme={null}
SELECT NOW();            -- '2024-06-15 14:30:00'  (DATETIME, session timezone)
SELECT SYSDATE();        -- same, but evaluated at call time, not statement start
SELECT CURRENT_TIMESTAMP; -- synonym for NOW()

SELECT CURDATE();        -- '2024-06-15'  (DATE only)
SELECT CURTIME();        -- '14:30:00'    (TIME only)
SELECT UTC_TIMESTAMP();  -- '2024-06-15 21:30:00'  (UTC)
```

`NOW()` 在语句开始时只求值一次——同一条 INSERT 中的所有行得到相同的时间戳。`SYSDATE()` 在每次被调用时求值。

## 格式化日期

`DATE_FORMAT` 使用格式字符串把日期或日期时间转换为字符串：

```sql theme={null}
SELECT DATE_FORMAT(NOW(), '%Y-%m-%d');          -- '2024-06-15'
SELECT DATE_FORMAT(NOW(), '%d/%m/%Y');          -- '15/06/2024'
SELECT DATE_FORMAT(NOW(), '%M %d, %Y');         -- 'June 15, 2024'
SELECT DATE_FORMAT(NOW(), '%Y-%m-%d %H:%i:%s'); -- '2024-06-15 14:30:00'
```

常见的格式说明符：

| 说明符 | 含义 | 示例 |
| :- | :- | :- |
| `%Y` | 4 位年份 | `2024` |
| `%y` | 2 位年份 | `24` |
| `%m` | 月份（01–12） | `06` |
| `%M` | 月份名称 | `June` |
| `%d` | 日（01–31） | `15` |
| `%H` | 小时（00–23） | `14` |
| `%i` | 分钟（00–59） | `30` |
| `%s` | 秒（00–59） | `00` |
| `%W` | 星期名称 | `Saturday` |
| `%w` | 星期（0=星期日） | `6` |
| `%j` | 一年中的第几天（001–366） | `167` |
| `%U` | 周数（0–53，周从星期日开始） | `24` |

## 将字符串解析为日期

`STR_TO_DATE` 使用同样的格式说明符把字符串转换为日期：

```sql theme={null}
SELECT STR_TO_DATE('15/06/2024', '%d/%m/%Y');         -- '2024-06-15'
SELECT STR_TO_DATE('June 15, 2024', '%M %d, %Y');     -- '2024-06-15'
SELECT STR_TO_DATE('2024-06-15 14:30:00', '%Y-%m-%d %H:%i:%s');  -- DATETIME
```

如果字符串与格式不匹配，则返回 NULL。

## 日期运算

**DATE\_ADD / DATE\_SUB** — 加上或减去一个时间间隔：

```sql theme={null}
SELECT DATE_ADD(NOW(), INTERVAL 7 DAY);        -- 7 days from now
SELECT DATE_ADD(NOW(), INTERVAL 3 MONTH);      -- 3 months from now
SELECT DATE_SUB(NOW(), INTERVAL 1 YEAR);       -- 1 year ago
SELECT DATE_ADD('2024-01-31', INTERVAL 1 MONTH); -- '2024-02-29' (end of Feb)
```

间隔单位：`SECOND`、`MINUTE`、`HOUR`、`DAY`、`WEEK`、`MONTH`、`QUARTER`、`YEAR`。

使用 `+` 和 `-` 运算符的简写形式：

```sql theme={null}
SELECT NOW() + INTERVAL 1 DAY;
SELECT '2024-06-15' - INTERVAL 1 MONTH;
```

**DATEDIFF** — 两个日期之间的天数：

```sql theme={null}
SELECT DATEDIFF('2024-12-31', '2024-06-15');  -- 199
SELECT DATEDIFF(NOW(), created_at) AS days_old FROM orders;
```

`DATEDIFF` 只计算天数，不计算时间。对于考虑时间的差值，请使用 `TIMESTAMPDIFF`：

```sql theme={null}
SELECT TIMESTAMPDIFF(HOUR, '2024-06-15 08:00', '2024-06-15 14:30');  -- 6
SELECT TIMESTAMPDIFF(MINUTE, created_at, NOW()) AS minutes_ago FROM events;
```

`TIMESTAMPDIFF(unit, from, to)` — 注意 `from` 在 `to` 之前。

## 提取日期部分

**EXTRACT / YEAR / MONTH / DAY**：

```sql theme={null}
SELECT YEAR(NOW());     -- 2024
SELECT MONTH(NOW());    -- 6
SELECT DAY(NOW());      -- 15 (same as DAYOFMONTH)
SELECT HOUR(NOW());     -- 14
SELECT MINUTE(NOW());   -- 30

-- EXTRACT uses interval unit names
SELECT EXTRACT(YEAR FROM NOW());        -- 2024
SELECT EXTRACT(HOUR FROM NOW());        -- 14
SELECT EXTRACT(YEAR_MONTH FROM NOW());  -- 202406
```

**DAYOFWEEK / DAYOFYEAR / WEEK**：

```sql theme={null}
SELECT DAYOFWEEK(NOW());   -- 7  (1=Sunday, 7=Saturday)
SELECT WEEKDAY(NOW());     -- 5  (0=Monday, 6=Sunday)
SELECT DAYOFYEAR(NOW());   -- 167
SELECT WEEK(NOW());        -- 23  (default mode 0: week 0–53, Sunday-based; mode 1 gives 24)
SELECT YEARWEEK(NOW());    -- 202423  (default mode)
```

## 截断到某个周期

要按月、周或日对数据分组，请把日期时间截断到周期边界：

```sql theme={null}
-- Group orders by month
SELECT DATE_FORMAT(created_at, '%Y-%m') AS month, COUNT(*) AS orders
FROM orders
GROUP BY month
ORDER BY month;

-- Group by week
SELECT YEARWEEK(created_at) AS week, COUNT(*) AS orders
FROM orders
GROUP BY week;

-- Truncate to start of month
SELECT DATE_FORMAT(NOW(), '%Y-%m-01');  -- '2024-06-01'
```

## Unix 时间戳

```sql theme={null}
SELECT UNIX_TIMESTAMP();                          -- seconds since epoch (session timezone)
SELECT UNIX_TIMESTAMP('2024-06-15 14:30:00');     -- datetime to epoch (session timezone)
SELECT FROM_UNIXTIME(1718451000);                 -- epoch to DATETIME
SELECT FROM_UNIXTIME(1718451000, '%Y-%m-%d');     -- epoch to formatted string
```

## 常见模式

最近 30 天的记录：

```sql theme={null}
SELECT * FROM orders WHERE created_at >= NOW() - INTERVAL 30 DAY;
```

当月的记录：

```sql theme={null}
SELECT * FROM orders
WHERE created_at >= DATE_FORMAT(NOW(), '%Y-%m-01')
  AND created_at <  DATE_FORMAT(NOW() + INTERVAL 1 MONTH, '%Y-%m-01');
```

根据出生日期计算年龄：

```sql theme={null}
SELECT TIMESTAMPDIFF(YEAR, birthdate, CURDATE()) AS age FROM users;
```

## 常见问题

#### NOW() 和 SYSDATE() 有什么区别？

`NOW()` 返回语句开始执行时的时间戳——单条 INSERT 或 UPDATE 中的所有行得到相同的值。`SYSDATE()` 返回它被调用那一刻的实际时钟时间，所以在循环中插入的行会得到不同的值。对于事务内一致性很重要的审计时间戳，`NOW()` 几乎总是正确的选择。

#### 为什么 DATE\_ADD 配合 INTERVAL 1 MONTH 在月末表现奇怪？

MySQL 会把日期限制在该月最后一个有效日。`DATE_ADD('2024-01-31', INTERVAL 1 MONTH)` 返回 `2024-02-29`（闰年）或 `2024-02-28`。这是预期的行为——不存在"2 月 31 日"。如果您需要可预测的月份运算，请先截断到月初。

## 故障排除

| 问题 | 解决方案 |
| :- | :- |
| `STR_TO_DATE` 返回 NULL | 格式字符串与输入不匹配——逐个核对每个格式说明符与对应的输入字符 |
| `DATEDIFF` 对同一天的时间戳返回 0 | `DATEDIFF` 忽略时间部分——同一日历日期的两行返回 0 |
| 日期比较漏掉了当天末尾的行 | `WHERE created_at <= '2024-06-15'` 止于午夜——使用 `< '2024-06-16'` 以包含完整的一天 |
| `TIMESTAMPDIFF` 返回意外的负值 | 参数顺序错误——是 `TIMESTAMPDIFF(unit, from, to)`，不是 `(unit, to, from)` |
| `WEEK()` 返回的数字与预期不同 | 周编号模式很重要（星期日还是星期一开始）——使用 `YEARWEEK(date, 3)` 获取 ISO 8601 周数 |

## 另请参阅

* [MySQL 中的时间戳与时区](https://villagesql.com/docs/zh/guides/timestamps-timezones.md) — 日期函数所操作的存储类型
* [MySQL BETWEEN](https://villagesql.com/docs/zh/tutorial/between.md) — 为什么日期范围用 `>=` 和 `<` 写更安全


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.