Flask-Migrate 初始化失败主因是db实例未正确初始化或未被发现：需在模块顶层声明db = SQLAlchemy()，并在create_app()中调用db.init_app(app)；FLASK_APP须指向含db和模型的可导入路径，且models必须被显式导入。
Flask-Migrate 初始化失败：找不到 db 实例怎么办
常见错误是运行 flask db init 后报 Working outside of application context，或提示 AttributeError: 'NoneType' object has no attribute 'metadata'。根本原因是 Flask-Migrate 没法自动发现你定义的 SQLAlchemy 实例。
- 确保在创建
db时用的是单例模式，不是函数内局部创建——比如不要写成def create_app(): db = SQLAlchemy(); return app，而要在模块顶层声明db = SQLAlchemy()，再在create_app()中调用db.init_app(app) -
FLASK_APP环境变量必须指向能完整导入db和模型的模块，例如export FLASK_APP="app:create_app"，而不是只指向app.py - 检查
models.py是否被 import 过——哪怕只是from . import models，否则db.metadata里没表，flask db migrate会生成空迁移脚本
生成迁移脚本后 flask db upgrade 报错：列已存在或约束冲突
这是最常踩的坑：Flask-Migrate 默认按模型定义“推断”变更，但对重命名字段、拆分表、改主键等操作无法自动识别，容易生成危险 SQL（比如先删原列再加新列，导致数据丢失）。
- 每次生成迁移后，务必打开
migrations/versions/*.py文件，人工核对upgrade()和downgrade()里的操作——特别是op.add_column()、op.drop_column()、op.alter_column() - 涉及字段重命名，别依赖自动检测，用
flask db migrate -m "rename user.email to user.contact_email"手动编辑迁移文件，改用op.alter_column(..., new_column_name="contact_email")（注意：SQLite 不支持，得用batch_alter_table） - 如果已有生产数据，禁止直接运行含
op.drop_column()的迁移；先备份，再考虑用op.execute("UPDATE ...")迁移数据，最后删旧列
多环境（dev/staging/prod）下迁移版本不一致怎么同步
开发机跑了 upgrade 到 rev abc123，线上却停在 def456，flask db upgrade 可能跳过中间版本或执行错顺序。
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 所有环境必须共用同一份迁移文件目录（
migrations/），不能各自init；Git 提交时确认该目录已纳入版本控制 - 上线前先运行
flask db current查当前版本，再用flask db history对比目标版本是否可达；若缺中间迁移，说明有人漏提交了migrations/versions/*.py - 生产环境升级前加
--sql参数预览 SQL：flask db upgrade head --sql，确认无 DROP TABLE 或隐式锁表操作
SQLite 迁移时遇到 no such table 或字段类型不生效
SQLite 对 ALTER TABLE 支持极弱，Flask-Migrate 在检测到 SQLite 时会自动启用 batch_alter_table 模式，但这要求你显式启用它，否则迁移会静默失败或忽略类型变更。
立即学习“Python免费学习笔记（深入）”；
- 在
env.py的run_migrations_online()函数里，确保context.configure(..., render_as_batch=True)已设置（Flask-Migrate ≥ 3.0 默认开启，老版本需手动加） - SQLite 不支持
ALTER COLUMN TYPE，所以String(50) → String(100)这类变长修改不会报错但也不生效；必须靠batch_alter_table+ 重建表实现，而重建表需要额外处理外键和索引 - 测试 SQLite 迁移时，用
flask db upgrade --sql看生成的 SQL 是否包含CREATE TABLE _alembic_tmp_...类语句——没有就说明 batch 模式没生效
迁移不是 set-and-forget 的黑盒，尤其当模型里有 UniqueConstraint、CheckConstraint 或复合索引时，Flask-Migrate 很可能漏掉它们，或者把约束名生成成随机哈希。这时候只能翻出数据库当前 schema，一行行比对迁移脚本。
