根本原因是模型未被导入导致Alembic无法识别变更；需确保models.py在db初始化后、migrate前被显式导入，且所有模型继承db.Model，否则metadata为空，迁移脚本将为空或仅含pass。
为什么 flask db migrate 没生成预期的模型变更？
常见现象是改了 models.py 里的字段（比如加了个 email = db.Column(db.String(120))），运行 flask db migrate -m "add email" 后，生成的迁移脚本里 upgrade() 为空，或只写了 pass。
根本原因是 Flask-Migrate 默认只跟踪 SQLAlchemy db.Model 子类中通过 db.Column 定义的字段 —— 但前提是这些模型类必须在执行命令前被 Python 解释器成功导入过。如果模型文件没被 app.py 或 __init__.py 显式导入，Alembic 就“看不见”变更。
- 检查你的应用初始化逻辑：确保
from . import models（或类似导入）出现在创建db实例之后、调用flask db init之前 - 避免在迁移命令执行时使用
if __name__ == '__main__':包裹模型定义 —— 这会让 Alembic 导入失败 - 临时验证方式：在 Python shell 中运行
from your_app import db; [c for c in db.metadata.tables.values()]，看是否列出所有表
flask db upgrade 报错 “Table already exists” 怎么办？
这是生产环境最常踩的坑：本地开发时建好表、写好迁移脚本，上线后直接 flask db upgrade，结果因数据库里已有旧表结构而失败。Alembic 默认认为迁移历史为空，试图从头建表。
正确做法不是删库重来，而是把当前数据库状态“标记”为已执行某次迁移：
立即学习“Python免费学习笔记（深入）”；
安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。
- 先用
flask db stamp head把当前数据库标记为最新迁移版本（适用于已有表结构与代码模型完全一致） - 如果结构不一致但想保留数据，先手动补全缺失字段（如用
ALTER TABLE user ADD COLUMN email VARCHAR(120)），再用flask db stamp <revision_id>标记对应迁移 ID - 查当前迁移 ID：运行
flask db history，找到你期望对齐的那个revision值（如abc123def456）
如何安全地修改主键或删除列？
SQLAlchemy 的自动迁移不支持主键类型变更、列删除等破坏性操作，默认生成的脚本会跳过这类改动，或生成不可执行的 SQL。必须手动编辑迁移文件。
关键原则：不能依赖 op.drop_column() 直接删列（某些数据库如 MySQL 会拒绝），也不能用 op.alter_column(..., nullable=False) 强制非空而不提供默认值。
- 删列前，先在
upgrade()里用op.add_column()加新列（如有需要），再用op.execute("UPDATE table SET new_col = old_col")迁移数据 - 确认数据无误后，在下一次迁移中再用
op.drop_column() - 改主键：通常需新建带新主键的表 → 复制数据 → 删旧表 → 重命名新表，全程用
op.execute()写原生 SQL - 所有手动 SQL 操作，务必在
downgrade()中提供逆向逻辑，否则回滚会失败
多分支协同开发时迁移文件冲突怎么解？
两个开发者各自运行 flask db migrate，生成了不同名字的迁移文件（如 abc123_add_profile.py 和 def456_add_avatar.py），Git 合并后，flask db upgrade 可能因执行顺序错乱报错。
Alembic 要求迁移链是线性的，不能有分叉。解决方法不是强行合并脚本，而是“融合迁移”：
- 先
flask db downgrade -1回退到最后一个共同父迁移 - 然后运行
flask db migrate -m "merge profile and avatar changes"，它会对比当前模型与数据库状态，生成一个包含全部变更的新迁移 - 删掉那两个冲突的旧迁移文件（注意：确保它们还没在任何环境执行过）
- 提交新迁移文件，并通知团队废弃旧迁移
真正麻烦的不是技术操作，而是团队得同步约定：谁负责 merge 迁移、何时停写模型、有没有人已在测试环境跑过某次迁移 —— 这些没法靠工具自动解决。
