flask-migrate不自动执行迁移，需手动触发flask db migrate和upgrade；未生成变更主因是模型未导入导致metadata为空，或数据库状态与迁移历史不一致。
Flask-Migrate 本身不自动执行迁移，它只帮你生成和应用迁移脚本；真正的“自动”必须由你明确触发 flask db migrate 和 flask db upgrade，漏掉任一环节都会导致模型变更未生效。
为什么 flask db migrate 没生成预期的变更？
常见原因是 Flask-Migrate 没正确识别到模型改动，或 SQLAlchemy 的 metadata 与数据库实际状态脱节。
- 确保所有模型类都已导入到
app.py或models.py被db实例注册的位置（比如在创建db后 import models） - 检查是否误用了
db.Table声明的纯表结构——这类表不会被flask db migrate追踪，只有继承db.Model的类才参与自动检测 - 如果刚初始化项目，先运行
flask db init创建migrations/目录，否则migrate会报错 “No such command” - 使用
flask db migrate -m "add user email"而不是只敲flask db migrate，避免因空消息导致生成失败（某些版本会静默跳过）
flask db upgrade 报错 “Target database is not up to date” 怎么办？
这说明当前数据库的 alembic_version 表记录的版本号，和 migrations/ 下最新脚本的 revision 不一致——通常发生在手动改过数据库、或多次迁移后跳过了某步。
- 先用
flask db history查看所有 migration 记录及其状态 - 用
flask db current确认数据库当前标记的 revision - 若只是本地开发环境，可安全执行
flask db stamp head强制把数据库标记为最新版（不执行 SQL），再跑upgrade——但生产环境严禁这样做 - 如果某次 migration 脚本执行失败（比如加了非空字段没给默认值），需手动编辑该脚本里的
upgrade()函数，补上server_default或先用op.alter_column(..., nullable=True)过渡
如何让迁移适配不同环境（dev/staging/prod）？
Flask-Migrate 默认读取 current_app.config['SQLALCHEMY_DATABASE_URI']，所以关键在于启动命令时加载对应配置，而不是在迁移脚本里硬编码。
- 用
FLASK_ENV=development flask db migrate或FLASK_ENV=production flask db upgrade，确保create_app()返回的 app 已根据环境变量加载了正确的数据库 URI - 避免在
manage.py或入口文件里直接写死app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///dev.db'，否则迁移永远只作用于开发库 - CI/CD 中执行迁移时，务必确认环境变量已注入，且数据库服务可连通——
flask db upgrade失败常因连接超时，而非 SQL 错误
最易被忽略的是：每次修改模型后，flask db migrate 生成的脚本必须人工审查。Alembic 无法智能推断业务语义，比如字段重命名会被识别为“删旧列 + 加新列”，丢失历史数据；这时候得手动把 op.drop_column 和 op.add_column 改成 op.alter_column(..., new_column_name=...)。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
