Flask 使用 ASGI 服务器部署：asgiref WsgiToAsgi 适配器实战解析

Flask 本质上是一个 WSGI 应用，但如果你希望将其运行在 ASGI 服务器上（例如 Hypercorn），就需要一个 WSGI 到 ASGI 的适配层。本文基于官方文档 deploying/asgi 展开，讲清楚如何用 asgiref 的 WsgiToAsgi 适配器包装 Flask 应用并交给 ASGI 服务器部署，并深入源码说明为什么官方推荐 asgiref——它与 Flask 自身 async/await 支持所使用的 async_to_sync 机制是同一套事件循环实现，还能解锁 WSGI 模式下无法完成的后台任务能力。

Flask 为什么是 WSGI 应用，而不是 ASGI 应用

从源码结构看，Flask 应用的入口就是标准的 WSGI 可调用对象。wsgi_app 是真正处理 WSGI environ、推送请求上下文并分发请求的方法，而 Flask.call 只是转发到 wsgi_app：

def __call__(self, environ, start_response):
    """The WSGI server calls the Flask application object as the
    WSGI application. This calls :meth:`wsgi_app`, which can be
    wrapped to apply middleware.
    """
    return self.wsgi_app(environ, start_response)

因此，当 ASGI 服务器（如 Hypercorn、Daphne）启动时，它期望的是接收 (scope, receive, send) 的 ASGI 可调用对象，直接传一个 Flask 实例并不匹配接口。必须经过一层 WSGI-to-ASGI 适配：适配器把 ASGI 协议转换回 WSGI environ，调用 Flask 的 __call__，再把 WSGI 响应转回 ASGI 的 send 消息流。这正是 deploying/asgi 文档的核心内容。

用 WsgiToAsgi 包装 Flask 应用

官方文档推荐的适配器是 asgiref 提供的 WsgiToAsgi。用法只需在应用定义完成后加一行包装：

from asgiref.wsgi import WsgiToAsgi
from flask import Flask

app = Flask(__name__)

...

asgi_app = WsgiToAsgi(app)

然后用 ASGI 服务器部署 asgi_app，官方示例使用 Hypercorn：

$ hypercorn module:asgi_app

其中 module:asgi_app 遵循「Python 模块路径:变量名」的形式，Hypercorn 会导入 module 并取出名为 asgi_app 的对象作为 ASGI 入口。

为什么官方推荐 asgiref 适配器

deploying/asgi 文档给出的推荐理由是：asgiref 适配器「与 Flask async 支持所使用的 event loop 集成」。这句话在源码中有直接证据。

Flask 从 2.0 起支持在视图、错误处理器、before/after request 钩子中使用协程函数（前提是通过 pip install flask[async] 安装）。pyproject.toml 中定义了这个可选依赖：

[project.optional-dependencies]
async = ["asgiref>=3.2"]

而 Flask 把 async def 视图转成同步可调用的核心实现，就在 Flask.async_to_sync：

def async_to_sync(self, func):
    try:
        from asgiref.sync import async_to_sync as asgiref_async_to_sync
    except ImportError:
        raise RuntimeError(
            "Install Flask with the 'async' extra in order to use async views."
        ) from None

    return asgiref_async_to_sync(func)

可以看到，Flask 内部就是用 asgiref 的 async_to_sync 来运行协程视图的：每当 WSGI 工作线程收到一个命中异步视图的请求，Flask 会在线程内启动事件循环、运行视图协程并等待结果返回（这一行为在 async-await 文档 的 Performance 一节有详细说明）。ensure_sync 则在 src/flask/app.py 中作为统一入口：普通 def 函数原样返回，async def 函数走 async_to_sync 包装。信号分发处（如 request_started、got_request_exception）也都通过 _async_wrapper=self.ensure_sync 保证钩子函数兼容同步与协程两种写法。

因此选择 asgiref 的 WsgiToAsgi 适配器，意味着「Flask 内部跑协程的机制」和「ASGI 服务层的适配机制」来自同一库、共享同一套事件循环语义，行为最一致，也最不容易出现事件循环嵌套、ContextVar 传播之类的边界问题。

ASGI 部署能解锁的能力：后台任务

WsgiToAsgi 的价值不只是「能跑起来」。async-await 文档 的 Background tasks 一节指出：Flask 作为 WSGI 应用，异步视图跑在一个随请求启停的事件循环里——当视图协程完成、事件循环停止时，任何未完成的 asyncio.create_task 后台任务都会被取消，因此「不能在视图里 spawn 后台任务」。

而 asgiref 的 WsgiToAsgi 适配器会创建一个持续运行的事件循环，所以用 ASGI 服务器加该适配器部署 Flask 后，就可以在视图中通过 asyncio.create_task 等方式派生后台任务了。文档原文（Background tasks 一节）即推荐这一组合。

需要注意的性能与适用边界

ASGI 部署并不等于性能提升。async-await 文档 给出了明确结论：

• 每个请求（包括命中异步视图的请求）仍然占用一个 worker；ASGI 包装后 Flask 依然走「一个请求一个 WSGI 工作线程」的模型，并发能力不会因此变化；
• Async 本身并不比同步代码更快，它的收益体现在 IO 密集型并发场景（并发查库、并发调用外部 API），对 CPU 密集型任务帮助有限；
• 如果你的代码库以异步为主，文档建议评估基于 ASGI 标准重写的 Quart，或继续使用 Gevent 跑 Flask（见 gevent 文档），再决定技术路线。

另外提醒两点适用前提：

1. asgiref 并非 Flask 的核心依赖，只有在安装 flask[async] 或显式安装 asgiref（pyproject.toml 要求 asgiref>=3.2）后才可用；若使用了异步视图却未安装，async_to_sync 会抛出带明确指引的 RuntimeError。
2. 无论用哪种服务器，生产环境都不要使用 Flask 自带的开发服务器——deploying 总览 强调开发服务器「不旨在安全、稳定或高效」，仅用于本地开发。

相关源码与测试索引

• deploying/asgi：本文所依据的官方文档，WsgiToAsgi 包装与 Hypercorn 启动命令的权威出处；
• deploying/index：部署总览，说明 WSGI 服务器、反向代理与托管平台的关系；
• async-await：async 视图原理、性能边界、后台任务与 ASGI 适配器的关系；
• Flask.ensure_sync / async_to_sync：Flask 借助 asgiref 运行协程视图的源码实现；
• Flask.wsgi_app / call：被适配器包装的 WSGI 入口；
• tests/test_async.py：asgiref 在场时对异步路由、异步错误处理器、异步 View/MethodView 的测试（通过 pytest.importorskip("asgiref") 控制），可用来验证异步视图在适配链路下的正确性；
• pyproject.toml：async 可选依赖与 asgiref>=3.2 版本约束。

总结：当你需要用 ASGI 服务器承载 Flask 应用，或希望在视图中安全地派生后台 asyncio 任务时，标准做法就是 asgi_app = WsgiToAsgi(app) 后交给 Hypercorn 等 ASGI 服务器；理解 Flask.async_to_sync 的实现后，你会明白 asgiref 适配器与 Flask 异步机制的协同是官方推荐的根本原因。