Flask 自 0.11 起推荐使用内置 CLI 而非 Flask-Script，需通过工厂函数创建可导入的 app 实例，用 @app.cli.command() 注册命令，并在命令中显式调用 with app.app_context() 确保配置与扩展可用。
如何用 Flask-Script 或 Flask CLI 注册自定义命令
Flask 自 0.11 起内置了 flask 命令行接口，不再推荐用已停止维护的 Flask-Script。直接依赖 Flask 自带的 CLI 支持更轻量、兼容性更好。
关键点是确保你的应用实例能被 CLI 发现：必须通过 app = create_app() 这类工厂函数构造，且在模块顶层可导入（不能藏在 if __name__ == '__main__': 里）。
- 在应用包根目录下设
app.py或__init__.py，导出app实例或create_app工厂函数 - 用环境变量指定入口：
FLASK_APP=app:create_app FLASK_ENV=development flask --help - 命令注册统一走
@app.cli.command()装饰器，不是@manager.command
为什么 runserver 之外的命令总提示 “No such command”
常见原因是 CLI 找不到应用上下文——flask 命令启动时不会自动执行 app.run()，也不会触发 create_app() 中的初始化逻辑（比如数据库连接、配置加载），除非你显式调用 with app.app_context():。
自定义命令里如果涉及数据库操作、配置读取或扩展初始化，必须手动激活上下文：
立即学习“Python免费学习笔记（深入）”；
@app.cli.command()
def init_db():
with app.app_context():
db.create_all()
print("Database initialized.")
- 漏掉
with app.app_context():→RuntimeError: Working outside of application context. - 用
app.test_request_context()替代？不行，它只模拟请求上下文，不包含应用级配置和扩展初始化 - 若命令需接收参数，用
@click.option('--force', is_flag=True)，别手写sys.argv解析
如何让 CLI 命令支持不同环境配置（dev/staging/prod）
CLI 本身不管理环境，靠 FLASK_ENV 和 FLASK_CONFIG 环境变量驱动配置加载逻辑，但命令内部仍需主动适配。
典型做法是在 create_app() 中根据 os.getenv('FLASK_CONFIG') 加载对应配置类，而 CLI 命令通过 current_app.config 读取生效配置：
@app.cli.command()
def show_config():
print(f"ENV: {current_app.config['ENV']}")
print(f"DEBUG: {current_app.config['DEBUG']}")
- 运行前必须设
FLASK_CONFIG=staging，否则默认用DevelopmentConfig -
FLASK_ENV=production会强制关闭调试器、启用更严格的错误处理，影响命令行为（如异常是否打印 traceback） - 避免在 CLI 命令里硬编码路径或密钥——全部走
current_app.config.get('XXX')
批量数据导入/清理类命令容易卡死或报错的原因
这类命令常因未控制事务边界、忽略大对象内存占用、或没处理信号中断而失败。
- 用
db.session.commit()替代db.session.flush()控制提交粒度；每 100 条提交一次，防长事务锁表 - 读大文件时用生成器逐行处理：
for line in open('data.csv'):比open().readlines()更省内存 - 捕获
KeyboardInterrupt并主动 rollback，避免留下脏数据：except KeyboardInterrupt: db.session.rollback(); raise - 生产环境执行前加
--dry-run开关预检，不真正写库
复杂命令的健壮性不在功能多，而在对上下文、事务、信号、配置隔离的处理是否显式可控。这些地方不写清楚，上线后半夜跑崩了才去翻日志，远比写命令本身花时间。
