Django __date 和 __month 查询失效原因及解决办法

Django 中 `__date`、`__month` 等时间字段查找失败，通常源于数据库时区支持缺失（尤其在启用 `USE_TZ=True` 时），而非代码或查询语法错误。

在 Django 中，DateTimeField 的 __date、__month、__year 等查找（lookup）依赖数据库对时区感知日期提取函数（如 MySQL 的 DATE()、MONTH()）的正确实现。当 settings.py 中配置了 USE_TZ = True（推荐生产环境启用），Django 会将所有 datetime 值以 UTC 存储，并在查询时依赖数据库准确解析带时区的时间戳为本地日期——这要求数据库本身具备完整的时区信息支持。

然而，许多 MySQL 实例（尤其是默认安装或 Docker 容器中的轻量版）*未初始化时区表（`mysql.time_zone）**，导致其无法正确执行CONVERT_TZ()或基于时区的日期截断操作。此时，Django 发出的类似WHERE DATE(CONVERT_TZ(end_date, '+00:00', @@session.time_zone)) = '2024-01-22'的 SQL 将返回空结果，即使数据真实存在——正如你所见：end_dateyear='2024'可用（年份提取不严格依赖时区转换），但date和__month` 全部返回空 QuerySet。

✅ 验证与修复步骤如下：

1. 确认问题根源
   登录 MySQL，检查时区表是否为空：

   SELECT COUNT(*) FROM mysql.time_zone;
   -- 若返回 0，则时区数据未加载

2. 加载系统时区数据（Linux/macOS）
   在数据库服务器上执行（需 root 或有 mysql 库写权限的用户）：

   mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql

   ⚠️ 注意：

   • /usr/share/zoneinfo 是常见路径，可通过 timedatectl status 或 ls /usr/share/zoneinfo 确认；
   • 若使用 Docker MySQL（如 mysql:8.0），需先进入容器并确保 zoneinfo 可用，或在启动时挂载并初始化；
   • 替换 root 为实际高权限账号，密码按提示输入。

3. 重启 MySQL 服务（部分版本需要）

   sudo systemctl restart mysql
   # 或 docker restart <mysql-container>

4. 验证修复效果

   # Python shell 中重试
   from datetime import date
   MembershipPlanSubscription.objects.filter(end_date__date=date(2024, 1, 22))
   # ✅ 现应返回匹配对象
   MembershipPlanSubscription.objects.filter(end_date__month=1)
   # ✅ 同样生效

? 补充建议：

• 若无法修改数据库（如共享主机），可改用 __range 模拟日期查询：

  from datetime import datetime, timedelta
  target_date = date(2024, 1, 22)
  start = datetime.combine(target_date, datetime.min.time())
  end = datetime.combine(target_date, datetime.max.time())
  MembershipPlanSubscription.objects.filter(end_date__range=(start, end))

• PostgreSQL 用户通常无需此操作（默认内置完整时区支持）；SQLite 则不支持 __date（Django 会退化为 Python 层过滤，性能差，不推荐用于生产）。

总之，__date 查找失效不是 Django Bug，而是数据库基础设施缺失所致。加载时区数据是根本解法，能一劳永逸恢复所有时区敏感查找（__date、__time、__hour、__week_day 等）的准确性。