Python Workers 正式全面可用

两年前，我们推出了 Python Workers，让开发者可以在 Cloudflare Workers 运行时中运行 Python 应用。我们的目标是让使用 Python 编写 Workers 像使用 TypeScript 一样简单，并让现有的 Python 包和框架生态“开箱即用”。

今天，Python Workers 正式发布（GA）。

GA 意味着什么？Python 如今已成为 Cloudflare 开发者平台上的一等、全面受支持的语言。你可以将自己熟悉的 Python 代码、库和设计模式无缝接入 Workers AI、R2、D1、Hyperdrive、Durable Objects、Queues、Workflows 以及 Cloudflare 平台的其他服务。你甚至可以在 Python Workers 内部运行 FastAPI、Django 和 Flask 等流行的 Python 框架。你还能利用Dynamic Workers 在一个 Worker 内部创建另一个 Python Worker。

from fastapi import FastAPI, Request
from workers import asgi, WorkerEntrypoint

app = FastAPI()

@app.get("/")
async def root(request: Request):
    env = request.scope["env"]
    return await env.AI.run(
        "@cf/openai/gpt-oss-120b",
        {
            "instructions": "You are a friendly assistant.",
            "input": "What is the origin of the phrase Hello, World?",
        },
    )

Default = asgi.entrypoint(app)

Python Workers 背后的历程

将 Python 引入 Cloudflare Workers 是一个自然的选择。由于 Workers 自 2018 年起就支持WebAssembly，这为我们运行基于 Wasm 编译的 Python 解释器提供了理想的环境。借助Pyodide，我们得以在 Cloudflare Workers 中快速支持广泛的 Python 应用。

我们的目标是打造首个支持无限扩展的 Python 应用平台，同时保持与在任何地方开发 Python 应用一样易用和高性能。

今天要介绍的功能是这项多年努力的成果。许多开发者已经在用 Python Workers 构建应用，而现在，我们正式让这些能力对所有人达到生产可用。

Python 现在是 Cloudflare Workers 运行时中的一等公民语言

Python Workers 现在原生支持 Cloudflare 开发者平台的 bindings。此前，在 Python Workers 中使用这些 bindings 时，需要在 RPC 边界显式地把 Python 对象转换为 TypeScript 对象。比如，要把一个 Python 字典发送到 Cloudflare Queue，需要写这样的胶水代码：

from pyodide.ffi import to_js
import js

self.env.QUEUE.send(to_js({"key": "value"}, dict_converter=js.Object.fromEntries))

这意味着 Python 开发者在写 Workers 时还得惦记 JavaScript 环境和相关代码，无论是人还是 AI agent 都很容易在这里出错。为了解决这个问题，我们把整个类型转换过程封装进了 Workers 运行时和 Python SDK。现在你可以用纯 Python 的方式使用所有 Cloudflare bindings，一行 JavaScript 都不用写，下面的代码直接就能跑：

self.env.QUEUE.send({"key": "value"})

Web 框架：FastAPI、Django 和 Flask

你现在可以在 Python Workers 中使用自己熟悉的 Python 框架（如 FastAPI、Django 或 Flask）来构建 API 服务器。我们实现了一个内置连接器，可以轻松把你的 Web 应用接入 Python Workers。

假设你有一个简单的 FastAPI 应用：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    message = "Hello, world!"
    return {"message": message}

在原生环境中，你需要用 uvicorn 之类的 web 服务器来运行它：

$ uvicorn main:app

而在 Python Workers 中，只需在代码里加上下面这段，就能用我们提供的 workers.asgi 包运行同一个应用：

from workers import asgi

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return await asgi.fetch(app, request, self.env)

# or equivalently
Default = asgi.entrypoint(app)

同理，你可以使用 workers.wsgi 包来运行 Django 等同步 Web 应用程序。

from workers import WorkerEntrypoint, wsgi
from your_django_app.wsgi import app

Default = wsgi.entrypoint(app)

那么底层机制是怎样的？

Python 为 Web 应用与 Web 服务器之间的通信定义了标准接口，即 Web 服务器网关接口（WSGI），及其现代异步对应物 ASGI。这一标准让开发者能够构建完全独立于服务器的应用程序。在传统部署中，Uvicorn 或 Gunicorn 等 Web 服务器负责处理多路并发客户端连接，通过线程扩展流量；而 FastAPI 等 Web 框架则只需专注于应用逻辑。

在 Cloudflare Workers 中，Workers 平台本身充当 Web 服务器。由于我们的全球网络已经无缝实现了负载均衡和无限扩展，无需在 Python Workers 内部重新发明轮子、运行独立的服务器。

相反，我们的 workers.asgi 和 workers.wsgi 连接器充当了一个轻薄且优化的桥梁。它们将传入的原生 JavaScript 请求转换为 Python 应用所期望的标准 WSGI/ASGI 结构，并以最小开销将响应无缝传回。通过这种方式，Python 开发者能够兼得两者优势：你可以使用喜欢的 Web 框架编写和整理代码，同时让 Cloudflare Workers 平台在全球范围内即时扩展你的 API，全程无需配置服务器。

这些连接器不仅适用于 FastAPI、Django 或 Flask，还兼容任何使用 WSGI 或 ASGI 接口的 Python Web 框架。

关于使用各 Web 框架的更多信息，请参阅 Python Workers 文档。

通过 Hyperdrive 使用 PostgreSQL 和 MySQL

如果你正在构建使用 PostgreSQL 或 MySQL 等关系型数据库的 Python 应用程序，现在可以将 Hyperdrive 集成到 Python Workers 中。

此前，Python Workers 不支持 TCP 套接字，导致数据库驱动无法使用。要理解这为何会成为阻碍，需要了解 WebAssembly 的运行机制。像 aiomysql 或 asyncpg 这样的 Python 数据库驱动依赖标准库中的 socket 模块来建立连接。在标准环境中，该模块通过 POSIX 系统调用与底层操作系统交互。而在 WebAssembly 沙箱内，这些用于网络通信的 POSIX 系统调用通常只是存根，始终会失败。任何尝试打开标准套接字的操作都会立即失败。为了解决这个问题，我们基于 Workers 的 connect API 实现了套接字系统调用。

当数据库驱动尝试建立 TCP 连接时，会经过我们自定义的套接字系统调用实现。它会将 Python 标准套接字操作（如建立连接、读取字节）翻译为 Workers 运行时使用的相应 JavaScript 调用。由于这种转换发生在系统调用层面，你的数据库驱动完全无需了解底层实现细节。

这个套接字桥梁使得我们的 Hyperdrive 集成成为可能。要在 Python Workers 中使用 Hyperdrive，首先通过 Hyperdrive 连接数据库，并在 Wrangler 配置文件中设置绑定：

"hyperdrive": [
    {
        "binding": "HYPERDRIVE_MYSQL",
        "id": "<example id: 57b7076f58be42419276f058a8968187>",
    }
]

然后，使用你熟悉的数据库驱动连接到 Hyperdrive：

import aiomysql

from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        hd = self.env.HYPERDRIVE_MYSQL
        conn = await aiomysql.connect(
            host=hd.host,
            port=int(hd.port),
            user=hd.user,
            password=hd.password,
            db=hd.database,
            ssl=None,
        )

        cur = await conn.cursor()
        await cur.execute("SELECT username FROM user")
        r = await cur.fetchall()
        await cur.close()
        conn.close()

你可以参考Hyperdrive Python Workers 文档 ，了解如何在 Python Workers 中使用 Hyperdrive，以及当前支持哪些包。

扩展 WebAssembly 包生态

Python Workers 运行在 WebAssembly 沙箱中，因此任何带有原生 C/C++/Rust 扩展的包都必须交叉编译为 WebAssembly 才能在 Python Workers 里运行。但此前并没有一套标准的方案可以把 Python 包交叉编译到 WebAssembly，我们的团队只能手动编译并托管自定义的 WebAssembly 包，这严重限制了 Python Workers 中实际可用的包的数量。

我们希望解决这个问题，让用户能用上更多样的包。但我们不想只构建仅限 Python Workers 使用的包——那样对社区没有好处。由于 Python Workers 构建在 Pyodide 之上，我们希望生态的发展能够惠及 Pyodide 以及整个 Python-on-WebAssembly 社区。

为此，我们提出了 PEP 783，为在浏览器运行时中运行 Python 定义了一个名为 PyEmscripten 的标准化平台。经过一年多的讨论和完善，该提案最终获得通过，包维护者由此可以为 PyEmscripten 平台构建并发布包，使其在所有实现了 PyEmscripten 的环境中通用。

我们还稳定了现有的 Pyodide 构建工具链，并将其演进为对所有包维护者开放的形式，让开发者能够轻松为 PyEmscripten 平台构建包。此外，我们在 cibuildwheel 中加入了对 PyEmscripten 平台的支持，方便更多人采纳这一平台。

虽然生态仍在逐步采用这一标准，但我们希望未来每个 Python 包都能有适配 WebAssembly 的 wheel 包。我们也正在与主要包的维护者积极合作，添加 PyEmscripten 构建。如果遇到尚不支持的包，欢迎在 Discord 或 GitHub 上告诉我们，我们的团队会尽力完成构建。

你也可以观看我们的 EuroPython 2026 演讲：“Python Everywhere: The State of Python on WebAssembly”，了解这一切是如何实现的。

用 Python 构建 AI agent 和流水线

丰富的数据科学和机器学习包生态，让 Python 成为构建智能体与 AI 流水线的自然选择。但过去，要在 Python Workers 中运行这类库往往面临难题：像 openai 和 langchain 这类库依赖 requests 或 httpx 等 HTTP 客户端来调用外部 API，而 Python Workers 当时缺乏底层 socket 操作支持，导致这些客户端无法正常工作。

为解决这一问题，我们向上游社区贡献代码，让此类 HTTP 客户端能在 WebAssembly 环境中直接通过 JavaScript 的 fetch API 发送请求。结合上一节此前介绍的底层 socket 操作支持，这使整个网络栈都能在 Python Workers 中无缝运行。

现在，你可以在 Python Workers 中原生运行 openai、langchain 和 mcp 等 AI 库。你还可以将这些库与 Workers AI 结合，在 Cloudflare 网络上进行无服务器 GPU 推理，或者通过 Cloudflare AI Gateway 代理请求。

下方示例展示了如何使用 langchain-cloudflare 包在 langchain 中运行 Worker AI 模型：

from langchain_cloudflare import ChatCloudflareWorkersAI
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import PromptTemplate
from workers import Response, WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        prompt = PromptTemplate.from_template(
            "In one sentence, describe a great day in the life of an {profession}."
        )
        llm = ChatCloudflareWorkersAI(
            model_name="@cf/meta/llama-3.3-70b-instruct-fp8-fast",
            binding=self.env.AI,
            max_tokens=64,
        )
        chain = prompt | llm | StrOutputParser()

        result = await chain.ainvoke({"profession": "electrician"})
        return Response.json({"result": result})

当下可用的构建方案

我们在 python-workers-examples 仓库中整理了一系列可直接用于生产环境的模式。以下是将 Python Workers 与 Cloudflare 生态系统结合的几种方式。

异步 AI 编排

开发全栈 AI 应用通常需要连接存储、消息队列和推理等多个服务。这个示例展示了如何完全在 Python Workers 中构建一个由 AI 驱动的图像生成器（image-to-image generator）。它接收用户请求，将其放入 Cloudflare Queue，并通过 Workflows 调用 Workers AI 来编排图像生成步骤，最后将图像存储到 R2 存储桶中。

使用 Bluesky Jetstream 进行实时流处理

消费海量实时事件流通常需要一台专用服务器来维持连接。在这个示例中，我们使用Python Worker 连接 ATProto/Bluesky Jetstream WebSocket。通过用 Durable Object 为该连接提供支持，Python Worker 能够维护长期状态，确保 WebSocket 连接保持活跃。

更多可探索的示例

Model Context Protocol (MCP) 服务器

使用官方 Python MCP 包构建并部署 MCP 服务器，让 AI 助手能够访问边缘数据。

结合 Vectorize 的检索增强生成（RAG）系统

使用 Workers AI 和 Vectorize（Cloudflare 的向量数据库）构建 RAG 系统。

Cloudflare 开发者文档中的 Python 代码示例

我们已在 Cloudflare 各产品的文档中补充了 Python 示例代码。凡是原来有 TypeScript 代码示例的地方，几乎都加上了对应的 Python 示例。我们会持续在所有产品的文档中提供 Python 示例。在整个开发者文档中，你都可以在 JavaScript、TypeScript 和 Python 之间切换代码示例。

接下来有什么计划？

正式发布只是起点。我们还有许多计划来改进 Python Workers，包括提升性能、优化内存占用，以及支持更多软件包。

欢迎继续告诉我们你想用 Python Workers 构建什么，我们会不断突破可能的边界。查看 Python Workers 文档，开始构建你的第一个 Python Worker 吧！