Flask-Migrate初始化失败主因是env.py未正确导入已绑定app的db实例；migrate不生成变更因db.metadata未更新；“Table already exists”源于多人各自生成迁移脚本；String长度变更需手动编辑迁移文件并实现downgrade。
Flask-Migrate 初始化失败：alembic env.py 里没配置 db 实例
常见错误是运行 flask db init 成功，但后续 flask db migrate 报 AttributeError: 'NoneType' object has no attribute 'metadata'。根本原因是 flask-migrate 没拿到你的 db 实例。
关键点在于 migrate 对象初始化时必须传入已绑定 app 的 SQLAlchemy 实例：
- 不要在
extensions.py或全局模块里只定义db = SQLAlchemy()就完事 - 必须确保
Migrate(app, db)中的db已完成init_app(app)（如果是工厂模式）或直接绑定了 app（单模块写法） -
env.py里默认从app.py或__init__.py导入db，路径写错、导入循环、或导入的是未初始化的空实例都会导致失败
flask db migrate 不生成变更：模型改了但 autogenerate 检测不到
flask db migrate 依赖 Alembic 的 autogenerate 功能对比当前模型与数据库 schema。它不读 Python 源码 AST，而是通过 db.metadata 和目标库实际结构做 diff —— 所以你改了模型，但 db.metadata 没更新，它就“看不见”变化。
- 确认所有模型类都 import 到了
db被初始化的模块作用域里（比如models.py在__init__.py中被导入） - 检查模型类是否继承自
db.Model，而不是Base或其他声明基类 - 如果用了
__table_args__或Index，确保语法合法；非法定义会导致metadata构建失败，进而跳过该模型 - SQLite 下某些约束（如 CHECK）可能不被 Alembic 识别，建议开发期用 PostgreSQL 验证迁移逻辑
升级时报错 “Table xxx already exists”：多环境共享 migrations 文件夹
这个错误不是代码问题，是协作陷阱。当多人本地执行 flask db migrate，各自生成不同前缀的 xxx_add_column.py，再合并进 Git，上线后 flask db upgrade 就可能对已存在表重复建表。
立即学习“Python免费学习笔记（深入）”；
- 团队必须共用同一套
migrations/目录，禁止各自生成、禁止 .gitignore 掉它 - 每次合入新迁移脚本前，先
flask db upgrade本地验证能否跑通，再提交 - 生产环境执行前，务必确认
alembic_version表中记录的 revision 和当前migrations/下最新文件一致 - 若已出错，不要手动删表，用
flask db stamp head强制标记为最新（仅限开发/测试），生产环境应走回滚 + 修正迁移脚本
字段类型变更不生效：String(50) → String(255) 迁移被跳过
Alembic 默认不检测长度类参数变更（如 String(50) → String(255)），因为多数数据库不把长度视为 schema 级别变更，且 ALTER COLUMN 修改长度在某些 DB 上代价高或不支持。
- 这类变更需手动编辑自动生成的迁移文件，在
upgrade()中显式调用op.alter_column() - PostgreSQL 支持
op.alter_column(table_name, 'col', type_=sa.String(255))；MySQL 需加existing_type参数避免报错 - SQLite 基本不支持
ALTER COLUMN，得靠op.create_table()+ 数据迁移 +op.drop_table()绕过，慎用 - 更稳妥的做法：新增字段 → 迁移数据 → 删除旧字段，尤其涉及非空或默认值时
最常被忽略的是迁移脚本里的 downgrade() 函数——很多人只写 upgrade，结果回滚失败。哪怕只是改个字段长度，downgrade 也得能还原，否则线上事故没法退。
