本文详解如何在 SQLModel 中正确声明 timezone-aware datetime 字段，避免因混用 offset-naive 与 offset-aware datetime 导致的 TypeError: can't subtract offset-naive and offset-aware datetimes 错误。核心在于显式配置 SQLAlchemy 底层列类型以支持时区。
本文详解如何在 sqlmodel 中正确声明 timezone-aware datetime 字段，避免因混用 offset-naive 与 offset-aware datetime 导致的 `typeerror: can't subtract offset-naive and offset-aware datetimes` 错误。核心在于显式配置 sqlalchemy 底层列类型以支持时区。
在使用 SQLModel（基于 SQLAlchemy 和 Pydantic）构建 PostgreSQL 应用时，一个常见但易被忽视的问题是：Python 的 datetime 类型默认不携带时区信息（offset-naive），而 PostgreSQL 的 TIMESTAMP WITH TIME ZONE（或简写为 timestamptz）要求时区感知值。当模型字段声明为 datetime 并配合 default_factory=lambda: datetime.now(timezone.utc) 使用时，SQLModel 默认将其映射为 TIMESTAMP WITHOUT TIME ZONE —— 这会导致 SQLAlchemy/asyncpg 在插入带 tzinfo 的 datetime 实例时抛出类型不匹配错误：
TypeError: can't subtract offset-naive and offset-aware datetimes
根本原因在于：SQLModel 的 Field() 对 datetime 类型的自动推导仅生成 sa.DateTime(timezone=False)，无法兼容 datetime.now(timezone.utc) 等时区感知对象。
✅ 正确解法是绕过自动类型推导，通过 sa_column 显式指定带时区的 SQLAlchemy 列类型。需引入 sqlalchemy 并精确配置：
from datetime import datetime, timezone
import uuid
from sqlmodel import Field, SQLModel
from sqlalchemy import DateTime # ✅ 注意：导入的是 sqlalchemy.DateTime，非 python datetime
class User(SQLModel, table=True):
id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
phone_number: str = Field(max_length=255)
phone_prefix: str = Field(max_length=10)
# ✅ 关键修复：显式声明 timezone=True 的 SQLAlchemy 列
registered_at: datetime = Field(
sa_column=DateTime(timezone=True), # ← 核心配置
default_factory=lambda: datetime.now(timezone.utc)
)? 提示：sa_column=DateTime(timezone=True) 等价于 sa.Column(DateTime(timezone=True), nullable=False)；SQLModel 会自动处理 nullable 和 default 行为，无需重复声明。
? 重要注意事项：
- PostgreSQL 必须使用 timestamptz 类型（SQLModel + timezone=True 会自动对应）；若数据库列为 timestamp without time zone，即使 Python 端带时区也会被静默截断，引发逻辑错误。
- 不要依赖 datetime.utcnow() —— 它返回 offset-naive 时间，已弃用且无法满足时区一致性要求；始终使用 datetime.now(timezone.utc)。
- 若需兼容 SQLite（不原生支持时区），应避免 timezone=True，或通过应用层统一转为 UTC 字符串存储；生产环境强烈推荐 PostgreSQL 以获得完整时区支持。
- 所有读取的 registered_at 值将自动带 tzinfo=timezone.utc，可安全参与时区运算（如 astimezone() 转换本地时间）。
? 验证是否生效？运行以下代码检查生成的 DDL（以 SQLAlchemy 2.0+ 为例）：
from sqlalchemy import create_engine, text
engine = create_engine("postgresql://...")
print(User.__table__.columns["registered_at"].type) # 输出: DATETIME(timezone=True)总结：SQLModel 中 datetime 时区问题不是框架缺陷，而是类型映射的显式性设计使然。唯一可靠方案是主动通过 sa_column 指定 DateTime(timezone=True)，并确保 default_factory 返回 timezone-aware 实例。此举既保持代码清晰性，又完全兼容 PostgreSQL 的时区语义，从根源上规避 TypeError。
