tzlocal 在 Docker 中返回 UTC 的根本原因是基础镜像未配置 /etc/localtime 和 /etc/timezone，导致其回退到 UTC；正确解法是通过 symlink 和写入文件确保两者存在且匹配，而非仅设 TZ 环境变量。
tzlocal 在 Docker 容器里总是返回 UTC
根本原因不是 tzlocal 本身坏了，而是它依赖系统时区配置（/etc/localtime 和 /etc/timezone），而绝大多数基础镜像（如 python:3.11-slim）压根没设这个——它就 fallback 到 UTC。
常见错误现象：get_localzone() 返回 UTC，或抛 ValueError: Unable to determine timezone；用 datetime.now().astimezone() 却发现时间没按预期偏移。
- 确认容器是否真有时区文件：
ls -l /etc/localtime（应指向/usr/share/zoneinfo/Asia/Shanghai类路径） - 检查
/etc/timezone是否存在且内容为时区名（如Asia/Shanghai） - 别只改环境变量
TZ：Python 标准库和tzlocal都不读它（只有部分 C 库函数如strftime会看）
Dockerfile 里正确设置时区的三种方式
核心原则：让 /etc/localtime 是个真实文件（非 dangling symlink），且 /etc/timezone 存在并匹配。
- 推荐方案（兼容性最好）：
RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \ echo "Asia/Shanghai" > /etc/timezone - Alpine 镜像要额外装 tzdata：
RUN apk add --no-cache tzdata && \ cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime - 用
debian:slim等带tzdata的镜像时，可省略安装步骤，但 symlink 必须手动建
注意：不要用 ENV TZ=Asia/Shanghai 代替——tzlocal 不认这个。
立即学习“Python免费学习笔记（深入）”；
代码里绕过 tzlocal 的临时解法
如果暂时没法改镜像（比如用别人维护的基础镜像），又必须拿到正确时区对象，直接用 zoneinfo 更可靠。
- Python 3.9+：
from zoneinfo import ZoneInfo; tz = ZoneInfo("Asia/Shanghai") - 旧版本用
pytz：import pytz; tz = pytz.timezone("Asia/Shanghai")（注意别用pytz.utc或pytz.UTC混用） - 避免混合使用：
tzlocal.get_localzone()和ZoneInfo返回的对象类型不同，datetime.replace(tzinfo=...)时可能出错
这种写法绕过了系统探测逻辑，但也意味着你把时区硬编码进了业务逻辑——CI/CD 环境和本地开发不一致时容易翻车。
为什么 tzlocal 5.0+ 在容器里还是可能失败
新版 tzlocal（5.0 起）加了对 systemd 的探测逻辑，会尝试读 /run/systemd/timesync/timers.json 或调 timedatectl。但容器里通常没 systemd，反而触发更早的 fallback 到 UTC。
- 查版本：
pip show tzlocal，若 ≥5.0 且没 systemd，基本等于“主动放弃”系统探测 - 降级不是好办法：
pip install tzlocal==4.3.1可能暂时缓解，但治标不治本 - 真正可靠的解法仍是镜像层确保
/etc/localtime可靠存在——这是所有时区库的共同底线
最常被忽略的一点：Kubernetes Pod 的 securityContext.readOnlyRootFilesystem=true 会让 /etc/localtime symlink 失效（因为无法写入），这时候连 ln -sf 都没用，得用 initContainer 或 volumeMount 把时区文件挂进去。
