当 django 项目启用时区（`use_tz = true`）且后端数据库为 mysql 时，`__date`、`__month` 等日期提取查询可能始终返回空结果，根本原因在于数据库缺失或未正确加载时区转换表（time zone tables）。
Django 的 __date、__month、__year 等字段查找（field lookups）依赖数据库对 DATETIME 字段执行服务端时区感知的日期截断。当 USE_TZ = True 时，Django 会将 datetime 值以 UTC 存储，并在查询时要求数据库根据当前时区（由 TIME_ZONE 设置）将 end_date 转换为本地时间后再提取日期部分。但若 MySQL 未预装或未启用时区支持，该转换将失败——此时 __date='2024-01-22' 实际被翻译为类似 DATE(CONVERT_TZ(end_date, '+00:00', 'Asia/Shanghai')) = '2024-01-22' 的 SQL，而 CONVERT_TZ() 在缺失时区表时静默返回 NULL，导致所有比较失败，最终 QuerySet 为空。
✅ 验证是否为时区表问题：
在 MySQL 中执行：
SELECT CONVERT_TZ('2024-01-22 12:00:00', '+00:00', 'UTC');
-- 若返回 NULL，极大概率是时区表未加载✅ 解决方案：为 MySQL 加载时区信息
⚠️ 注意：此操作需具备 MySQL root（或有 mysql 数据库写权限）账户，且服务器已安装 tzdata（Linux）或对应时区数据包。
Linux / macOS（使用系统 zoneinfo）：
# 1. 确保已安装 tzdata（Ubuntu/Debian） sudo apt-get install tzdata # 2. 导入时区数据到 MySQL（路径可能因系统而异） mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql
Windows（MySQL Installer 用户）：
Docker Hub (hub.docker.com)。此技能适用于所有 Docker Hub 操作，包括读取、创建、更新和删除数据。只要任务涉及 Docker Hub，就使用此技能。
- 打开 MySQL Installer → 选择 “Reconfigure” → 在 “Advanced Options” 中勾选 “Install Time Zone Information” → 完成配置。
✅ 验证修复效果：
# Python shell from datetime import date from myapp.models import MembershipPlanSubscription # 应正常返回匹配对象 qs = MembershipPlanSubscription.objects.filter(end_date__date=date(2024, 1, 22)) print(qs.count()) # > 0 ✅ # 同样支持 __month、__year、__day 等 qs = MembershipPlanSubscription.objects.filter(end_date__month=1)
? 额外注意事项：
- PostgreSQL 和 SQLite 默认支持时区转换，通常无需手动干预；
- 若使用 Docker 部署 MySQL，请确保容器内已挂载 /usr/share/zoneinfo 并在启动脚本中执行 mysql_tzinfo_to_sql；
- 修改后重启 MySQL 服务非必需，但建议执行 FLUSH TABLES; 清理缓存；
- 开发环境可临时设 USE_TZ = False 快速验证是否为时区问题（仅限调试，切勿用于生产）。
通过正确配置数据库时区支持，__date 等查找即可恢复预期行为，既保持 Django 时区安全特性，又保障日期维度查询的准确性与可靠性。
