Python Workers 的工作原理

用 Python 编写的 Workers 由 Pyodide ↗ 执行。 Pyodide 是 CPython ↗（Python 的参考实现——通常简称为 "Python"）编译为 WebAssembly 的版本。

当你编写 Python Worker 时，你的代码由 Pyodide 在 V8 isolate 中直接解释。 请参阅 Workers 的工作原理了解更多信息。

基本的 Python Worker 包括一个带有继承 WorkerEntrypoint 的 Default 类的 Python 文件，例如：

from workers import Response, WorkerEntrypoint

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

...以及指向此 .py 文件的 Wrangler 配置文件：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hello-world-python-worker",
	"main": "src/entry.py",
	// Set this to today's date
	"compatibility_date": "2026-08-17"
}

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

当你运行 uv run pywrangler dev 进行本地开发时，Workers 运行时将：

1. 根据兼容性日期确定需要哪个版本的 Pyodide
2. 根据 pyproject.toml 文件安装任何必要的包
3. 为你的 Worker 创建新的 v8 isolate，并自动注入 Pyodide
4. 使用 Pyodide 提供你的 Python 代码

不需要额外的工具链或预编译步骤。Python 执行环境由 Workers 运行时直接提供，与用 JavaScript 编写的 Workers 的工作方式类似。

请参阅 Python 示例，了解如何在 Workers 中使用 Python。

为了减少冷启动时间，部署 Python Worker 时，Cloudflare 会在部署时尽可能多地预先完成昂贵的工作。当你运行 uv run pywrangler deploy 时，会发生以下情况：

1. Wrangler 将你的 Python 代码和 pyproject.toml 中包含的任何包上传到 Workers API。
2. Cloudflare 将你的 Python 代码发送到 Workers 运行时进行验证。
3. Cloudflare 为你的 Worker 创建新的 v8 isolate，并自动注入 Pyodide。
4. Cloudflare 执行 Worker 入口模块及其在顶层导入的所有内容，然后对 Worker 的 WebAssembly 线性内存进行快照。实际上，我们在部署时而不是运行时执行昂贵的初始化工作。
5. Cloudflare 将此快照与你的 Worker 的 Python 代码一起部署到 Cloudflare 网络。

当请求到达你的 Worker 时，我们加载此快照并使用它在 isolate 中引导 Worker，避免昂贵的初始化时间：

有关性能优化以及 Workers 运行时如何减少 Python Workers 冷启动的更多详情，请参阅介绍 Python Workers 的博客文章 ↗。

Python 每年 8 月发布新版本，Pyodide 在六（6）个月后发布新版本。 当 Pyodide 的新版本发布时，我们将通过兼容性标志将其添加到 Workers，该标志仅在指定的兼容性日期之后启用。 这让我们能够持续提供更新，而不会面临破坏性变更的风险，将我们对 JavaScript 的承诺扩展到 Python。

每个 Python 版本都有五（5）年支持窗口 ↗。 一旦某个 Python 版本的支持窗口过去，就不再应用安全补丁，使该版本不再安全。 遵循 Workers 运行时从不破坏已在生产环境中运行的应用程序的策略， 支持窗口之外的现有 Python Workers 将继续工作。 但是，我们不建议在新项目中使用支持窗口之外的 Python 版本， 我们也不会为使用这些版本产生的问题提供补丁。 我们也不能保证这些较旧的 Python 版本不会遭受性能下降， 包括更高的延迟或 CPU 时间使用。