flask 3.0 是破坏性升级，核心是架构收紧：移除 flask._compat 模块、强制 werkzeug ≥3.0.0、变更扩展初始化方式（如 sqlalchemy 需构造时绑定 app），并默认禁用 debug 模式下的自动重载器。
Flask 3.0 是一次破坏性升级，核心变化不是功能增强，而是架构收紧——它移除了大量为向后兼容而保留的旧接口和内部模块，导致很多扩展（尤其是未及时适配的第三方包）在导入或初始化阶段就直接失败。
flask._compat 模块被彻底删除
这是最典型的报错源头。大量老扩展（如 flask-script、flask-migrate 旧版）依赖 flask._compat 提供的 text_type、string_types 等工具，但 Flask 3.0 已将其整个模块移除。
- 错误现象：
ModuleNotFoundError: No module named 'flask._compat' - 真实原因：不是路径写错，是该模块物理上不存在了
- 不推荐降级 Flask 来迁就扩展——这会引发 Werkzeug/Jinja2 版本链式冲突
- 可行做法：定位扩展源码中 import 行（如
flask_script/__init__.py第15行），改用扩展自身维护的兼容层（如from flask_script._compat import text_type）
Werkzeug 3.0+ 导致的底层 API 断裂
Flask 3.0 强制要求 Werkzeug ≥ 3.0.0，而后者删除了 url_quote、escape（移到 markupsafe）、get_current_object 等函数。扩展若直接调用这些，就会抛 ImportError 或 AttributeError。
- 常见错误：
ImportError: cannot import name 'url_quote' from 'werkzeug.urls' - 检查方式：运行
pip show werkzeug，确认版本 ≥ 3.0.0；再查扩展文档是否声明支持 Werkzeug 3.x - 临时绕过（仅调试）：手动安装
werkzeug==2.3.9，但必须同步锁定flask==2.3.3，否则 Flask 启动即崩溃 - 长期方案：升级扩展本身（如
flask-migrate>=4.0.0已适配 Flask 3.0）
扩展初始化方式变更：从 app.init_app() 到 __init__ 参数注入
Flask 3.0 更强调“显式优于隐式”，部分扩展（如新版本 flask-sqlalchemy）不再接受裸 app 实例传入 init_app()，而是要求在构造时就绑定配置。
- 旧写法失效：
db = SQLAlchemy(); db.init_app(app) - 新写法要求：
db = SQLAlchemy(app)或db = SQLAlchemy(model_class=Model) - 影响范围：所有基于
flask-sqlalchemy、flask-login2.0+ 的扩展初始化逻辑 - 关键点：不是语法错，是对象生命周期管理逻辑变了——延迟初始化可能拿不到当前 app context
最易被忽略的是：Flask 3.0 默认禁用 debug=True 下的自动重载器（reloader），某些依赖 werkzeug.serving.make_server 的开发类扩展会静默失效，而不是报错——得看日志里有没有 * Debugger is active! 这行提示。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
