应用工厂模式下Flask-Migrate执行报错：run.py与manage.py命令排查

我之前在Flask应用工厂模式下用Flask-Migrate时也踩过一模一样的坑，核心问题基本都是Flask-Migrate无法正确定位到你的应用工厂函数，或者环境变量/代码配置有细节错误。咱们一步步拆解排查：

1. 环境变量的正确写法是关键 #

你之前尝试的run.create_app、run:create_app()都是错误格式！正确的环境变量设置应该是：

# Linux/macOS
export FLASK_APP=run:create_app
# Windows CMD
set FLASK_APP=run:create_app
# Windows PowerShell
$env:FLASK_APP = "run:create_app"

注意这里的规则：

• 用冒号分隔模块名和函数名，不是点
• 不需要加()，Flask会自动调用这个无参数的工厂函数（如果你的create_app需要参数，比如create_app(config_name)，得额外设置FLASK_APP=run:create_app('development')）

2. 检查manage.py的配置（如果用Flask-Script） #

如果你还在用python manage.py db init，得确保manage.py里正确初始化了应用和Migrate：

# manage.py 示例代码
from flask_script import Manager
from flask_migrate import Migrate, MigrateCommand
from run import create_app
from your_project.models import db  # 替换成你实际的db导入路径

# 先通过工厂函数创建app实例
app = create_app()
# 绑定db和app到Migrate
migrate = Migrate(app, db)
manager = Manager(app)
# 添加db命令
manager.add_command('db', MigrateCommand)

if __name__ == '__main__':
    manager.run()

如果你的db是用db.init_app(app)初始化的（应用工厂模式常见写法），一定要确保create_app()已经执行并返回了app实例，再绑定Migrate。

3. 用Flask CLI替代Flask-Script（推荐） #

Flask-Script已经停止维护，官方更推荐直接用Flask自带的CLI。这时候要确保你的应用工厂里正确初始化Migrate：

# run.py 示例代码
from flask import Flask
from flask_migrate import Migrate
from your_project.models import db

def create_app():
    app = Flask(__name__)
    # 加载配置（比如从配置文件或环境变量）
    app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///your_db.db'  # 替换成你的数据库URI
    app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
    
    # 初始化db
    db.init_app(app)
    # 初始化Migrate，必须在db.init_app之后
    Migrate(app, db)
    
    # 注册蓝图、添加其他扩展等操作...
    
    return app

设置好FLASK_APP=run:create_app后，直接执行：

flask db init

4. 其他容易忽略的细节 #

• 数据库配置错误：检查SQLALCHEMY_DATABASE_URI是否正确，比如SQLite的路径是否存在、MySQL/PostgreSQL的连接参数（用户名、密码、主机）是否正确
• 应用工厂函数的可访问性：确保create_app函数在run.py的顶级作用域，没有嵌套在其他类或函数里
• 依赖版本问题：确保Flask、Flask-SQLAlchemy、Flask-Migrate版本兼容，建议用pip freeze检查版本，或重新安装兼容版本

内容的提问来源于stack exchange，提问作者Gep Gecici