基础

如 Python Workers 简介 中所述，Python Worker 可以简单到只有四行代码：

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello World!")

与其他 Worker 类似，Python Worker 的主入口点是 fetch 处理器，它处理发送到 Worker 的传入请求。

在 Python Worker 中，此处理器放在继承 WorkerEntrypoint 类的 Default 类中（可从 workers SDK 模块导入）。

传递给 fetch 处理器的 request 参数是 JavaScript Request 对象，通过外部函数接口（FFI） 暴露， 允许你直接从 Python 代码访问它。

让我们尝试编辑 Worker 以接受 POST 请求。根据 Request 文档，我们知道可以在 async 函数中调用 await request.json() 将请求体解析为 JSON。

在 Python Worker 中，你可以这样写：

from workers import WorkerEntrypoint, Response
from hello import hello

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        body = await request.json()
        name = body["name"]
        return Response(hello(name))

许多其他 JavaScript API 可通过 FFI 在 Python Workers 中使用，因此你可以 以类似方式调用其他方法。

编辑 src/entry.py 后，Wrangler 会自动重启本地 开发服务器。

现在，如果你发送带有适当请求体的 POST 请求， Worker 将返回个性化消息。

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name": "Python"}' http://localhost:8787

Hello, Python!

要从 Python Worker 返回 JSON，使用 Response.json()：

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        data = {"message": "Hello", "status": "ok"}
        return Response.json(data)

WorkerEntrypoint 上的 env 属性可用于访问 环境变量、 secrets 和 绑定（binding）。

例如，让我们尝试在 Python Worker 中设置和使用环境变量。首先，在 Worker 的 Wrangler 配置文件 中添加环境变量：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hello-python-worker",
	"main": "src/entry.py",
	"compatibility_flags": [
		"python_workers"
	],
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"vars": {
		"API_HOST": "example.com"
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hello-python-worker"
main = "src/entry.py"
compatibility_flags = [ "python_workers" ]
# Set this to today's date
compatibility_date = "2026-08-17"

[vars]
API_HOST = "example.com"

然后，你可以通过 env 参数访问 API_HOST 环境变量：

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response(self.env.API_HOST)

Python Worker 可以拆分为多个文件。

让我们创建一个新的 Python 文件，名为 src/hello.py：

def hello(name):
    return "Hello, " + name + "!"

现在，我们可以修改 src/entry.py 以使用新模块。

from hello import hello
from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response(hello("World"))

编辑 src/entry.py 后，pywrangler 会自动检测更改并 重新加载 Worker。

workers-runtime-sdk 包为 Python Workers 提供运行时 SDK。 使用 pywrangler 时，此包会自动安装并包含在 Worker 中， 但你也可以手动安装以在 IDE 中利用类型提示和自动补全。

要启用它们，将 workers-runtime-sdk 包添加到 pyproject.toml 文件。

dependencies = [
  "workers-runtime-sdk"
]

此外，你可以使用 uv run pywrangler types 基于 Worker 配置生成类型

这包括基于绑定的 Env 类型、模块规则，以及基于 compatibility_date 和配置文件中的 compatibility_flags 的运行时类型。请参阅

要全局升级到最新版本的 pywrangler，运行以下命令：

uv tool upgrade workers-py

要在特定项目中升级到最新版本的 pywrangler，运行以下命令：

uv lock --upgrade-package workers-py

• 了解本地开发、部署以及 Python Workers 的工作原理 的详情
• 探索包（Packages） 文档，了解如何在 Python Workers 中使用包
• 了解 Python Workers 中支持 Python 标准库 的哪些部分
• 了解 Python Workers 的外部函数接口（FFI），以及如何使用它处理绑定（binding）和运行时 API