根本原因是alembic未正确加载模型：env.py中target_metadata未导入orm模型或存在多个base实例，导致无法比对模型与数据库结构；数据库连接指向空库或旧结构、__table_args__等不稳定写法也会使autogenerate失效。
为什么 alembic revision --autogenerate 总是生成空迁移文件
根本原因通常是 Alembic 没法正确比对当前模型与数据库实际结构。它依赖 target_metadata 中的 MetaData 对象，而这个对象必须和你 ORM 模型（比如用 SQLAlchemy 的 Base.metadata）完全一致。常见踩坑点：
- env.py 里没把模型模块 import 进来，导致 target_metadata 是空的
- 多个 Base 实例（比如分模块定义了不同 Base），但只传了一个的 .metadata
- 数据库连接 URL 指向的是空库或旧结构库，Alembic 拿不到真实 schema 做 diff
- 模型里用了 __table_args__ 或 Column(..., server_default=...) 等 Alembic 解析不稳定的写法，导致比对失效
实操建议：先手动执行 alembic revision -m "test"，再打开生成的文件看 upgrade() 里有没有 op.create_table()；如果没有，就回头检查 env.py 中 target_metadata 是否真正包含了所有模型表。
如何安全地在团队中同步迁移脚本
Alembic 本身不处理合并冲突，迁移文件一旦被多人修改就容易出问题。关键不是“怎么避免冲突”，而是“怎么让冲突可识别、可修复”：
- 所有迁移文件名必须带时间戳（用 alembic revision --autogenerate 默认生成的格式），禁止手改文件名
- 每次 alembic upgrade head 前，先 alembic current 确认本地版本，再 alembic history 查看远端新增了哪些 revision ID
- 如果发现别人已提交新迁移，但你的模型还没更新，先 git pull，再 alembic upgrade head，最后再跑自己的 --autogenerate
- 避免在同一个迁移里混入“删字段”和“加字段”，拆成两个独立 revision，方便回滚和审计
- 把 alembic_version 表纳入 CI 检查：部署前验证目标库的 alembic_version.version_num 是否等于预期 revision ID
alembic downgrade -1 回退失败，提示 “Can't locate revision identified by 'xxx'
这不是数据库问题，是 Alembic 自己的 revision 依赖链断了。典型场景：
- 你删掉了某个迁移文件，但 alembic_version 表里还存着它的 ID
- 多人协作时，有人 force push 覆盖了历史迁移文件
- down_revision 字段写错了（比如拼错 ID、写成 None 却该有父节点）
修复方式不是重装 Alembic，而是：先用 alembic history --verbose 列出完整链；确认断点位置后，手动编辑出问题的迁移文件，修正 down_revision；如果已丢失文件，就新建一个空迁移，把 down_revision 设为上一个存在的 ID，并在 upgrade() 里写 pass，downgrade() 里写实际要回退的操作——本质是补全依赖链。
生产环境执行 alembic upgrade head 的隐藏风险
最常被忽略的是 DDL 锁和长事务。Alembic 默认在单个事务里执行整个 upgrade()，但某些操作（如给大表加索引、改列类型）在 PostgreSQL/MySQL 上会锁表，导致服务假死：
- 不要直接在生产库跑含 op.alter_column() 或 op.create_index(..., unique=True) 的迁移
- 对 MySQL，用 op.execute("ALTER TABLE ... ALGORITHM=INPLACE, LOCK=NONE") 替代原生 alter_column
- 对 PostgreSQL，用 CONCURRENTLY 创建索引：op.execute("CREATE INDEX CONCURRENTLY ...")，注意它不能在事务块内运行，得把 autocommit_block = True 加到迁移函数上
- 所有涉及数据迁移的逻辑（比如用 op.bulk_insert() 补默认值），务必加 if context.get_x_argument(as_string=True).get('skip_data') 开关，方便紧急跳过
- 生产执行前，先在同规格从库上试跑，用 EXPLAIN 或 SHOW CREATE TABLE 验证语句行为
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
