企业官网建设流程全解析

Cloudflare Docs 深度解析：Python Workers 的python_no_global_handlers兼容性标志与入口类（Entrypoint Class）机制

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs

python_no_global_handlers是 Cloudflare 在 2025 年 8 月 14 日随 Python Workers 处理器结构变更一同引入的兼容性标志。本指南以该标志为主线，完整解析 Python Workers 从"模块级全局处理器"到"默认入口类"的演进、新旧两种写法的差异、wrangler.jsonc中的配置方法，以及这一变更背后的运行时原理。

读完本文，你将掌握：如何用新的WorkerEntrypoint入口类编写fetch/scheduled等处理器，何时需要显式开启或关闭python_no_global_handlers，以及该标志在 Cloudflare Docs 仓库中从声明（兼容性标志文档）到校验（配置 Schema）再到使用示例（变更日志）的完整落地链路。

一、标志概述：它到底做了什么

python_no_global_handlers是 Cloudflare Docs 仓库中维护的众多兼容性标志（Compatibility Flags）之一，其官方定义位于 src/content/compatibility-flags/python-no-global-handlers.md：

When thepython_no_global_handlersflag is set, Python Workers will disable the global handlers and enforce their use via default entrypoint classes.

翻译：当设置python_no_global_handlers标志时，Python Workers 将禁用全局处理器（global handlers），并强制通过默认入口类（default entrypoint classes）来使用处理器。

从声明文档的 Frontmatter 中可以提取出该标志的关键元数据：

需要特别注意的是该文档头部还包含一组构建控制元数据_build: publishResources: false / render: never / list: never，表明这类兼容性标志文档是纯数据源，不会被渲染为独立页面，而是由构建系统消费、并自动归并到兼容性标志总览中。

标志在仓库中的数据结构

仓库用 Zod Schema 对这类标志文档做了运行时校验，见 src/schemas/compatibility-flags.ts：

export const compatibilityFlagsSchema = z.object({ name: z.string(), enable_date: z.string().optional().nullable(), enable_flag: z.string().nullable(), disable_flag: z.string().optional().nullable(), sort_date: z.string(), experimental: z.boolean().optional(), });

从中可以看到每一个兼容性标志文档的标准字段模型：name、enable_date（可选）、enable_flag、disable_flag（可选）、sort_date，以及可选的experimental布尔标记。这解释了为什么每个标志通常都成对提供"开启"与"关闭"两个 flag 名称——enable_flag与disable_flag是 Schema 中的一等公民，允许开发者在新旧行为之间随时切换。

二、背景：从"全局处理器"到"入口类"的结构变更

要理解这个标志，必须回到同一天发布的官方变更日志 src/content/changelog/workers/2025-08-14-new-python-handlers.mdx：

We are changing how Python Workers are structured by default. Previously, handlers were defined at the top-level of a module ason_fetch,on_scheduled, etc. methods, but now they live in an entrypoint class.

即：旧写法是在模块顶层直接定义on_fetch、on_scheduled等全局处理器函数；新写法是把它们收敛进一个入口类（entrypoint class）中。默认行为在 2025-08-14 之后就是新写法，而python_no_global_handlers标志只是把这个"默认行为"显式化——设置它即声明"我不再用全局处理器，请强制校验入口类写法"。

新旧写法对比

变更日志给出了新的 fetch 处理器标准写法：

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

这段代码的要点：

• WorkerEntrypoint和Response均从workersSDK 模块导入；
• 类名必须为Default，这是 Python Workers 约定的"默认入口类"；
• 继承WorkerEntrypoint后，通过实现async def fetch(self, request)来处理入站请求。

对照旧写法，则是把on_fetch直接写在模块顶层：

# 旧写法（全局处理器） async def on_fetch(request, env, ctx): return Response("Hello World!")

两种写法实现的功能一致，但新写法把所有处理器封装在类的命名空间内，与 JavaScript Workers 中export default { fetch() {...} }的"入口对象"心智模型对齐，也让self.env等实例级状态（详见下文第四节）有了自然的挂载点。

三、如何配置该标志：wrangler 配置文件实战

方式一：依赖兼容性日期（推荐，零配置）

由于enable_date为 2025-08-14，当你的 Worker 的compatibility_date设置在该日期或之后时，新行为自动生效，无需在compatibility_flags中显式列出python_no_global_handlers。一个标准的 Python Worker 配置如下（出自 Python Workers 基础文档）：

{ "$schema": "./node_modules/wrangler/config-schema.json", "name": "hello-python-worker", "main": "src/entry.py", "compatibility_flags": [ "python_workers" ], "compatibility_date": "$today", "vars": { "API_HOST": "example.com" } }

注意其中compatibility_date使用占位符"$today"，构建时会被替换为实际日期；而"python_workers"标志是 Python Workers 处于 open beta 期间必须添加的另一个标志（详见 Python Workers 索引文档 中的 beta 提示）。此时由于日期已晚于 2025-08-14，python_no_global_handlers隐含生效。

方式二：显式声明新行为

如果你想在不依赖日期的情况下明确声明"使用入口类写法"，可以在wrangler.jsonc的compatibility_flags数组中显式加入"python_no_global_handlers"：

{ "compatibility_flags": [ "python_no_global_handlers" ] }

方式三：回退旧行为（关键逃生通道）

这是本标志最有实战价值的用途。如果你的代码仍在使用on_fetch/on_scheduled这类模块级全局处理器，或者你在维护一个尚未迁移的历史 Worker，则需要显式关闭新行为。变更日志 2025-08-14-new-python-handlers.mdx 明确给出了操作方式：

To keep using the old-style handlers, you can specify thedisable_python_no_global_handlerscompatibility flag in your wrangler file:

{ "compatibility_flags": [ "disable_python_no_global_handlers" ] }

三种方式的选择建议：

• 新项目：直接采用Default(WorkerEntrypoint)入口类写法，保持compatibility_date在 2025-08-14 之后，无需任何额外标志；
• 迁移中的项目：若代码尚未改完，先通过disable_python_no_global_handlers维持旧行为，平滑过渡后再移除该标志并迁移到入口类；
• 希望提前验证新行为：即使compatibility_date早于 2025-08-14，也可以显式添加python_no_global_handlers提前体验。

四、入口类的完整能力：不止 fetch

新结构的价值在于，Default(WorkerEntrypoint)不只是换了个写法，它还获得了与 JavaScript Worker 对齐的完整处理器能力与实例状态。

1. 处理 Cron 定时任务：scheduled

调度处理器同样收敛进入口类。仓库中 Scheduled Handler 文档 的 Python 示例即为：

from workers import WorkerEntrypoint class Default(WorkerEntrypoint): async def scheduled(self, controller, env, ctx): ...

当 Worker 通过 Cron Trigger 被调用时，运行时将调用该scheduled方法。本地开发时可以用下面的命令触发并验证：

curl "http://localhost:8787/cdn-cgi/local/scheduled?format=json"

2. 访问环境变量与绑定：self.env

WorkerEntrypoint上内置了env属性，可用于访问环境变量、Secrets 以及各类 Bindings。示例（出自 basics.mdx）：

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

这里API_HOST即配置文件中vars块声明的环境变量（见第三节的wrangler.jsonc示例）。

3. 返回 JSON 响应

使用Response.json()可以直接序列化 Python 字典：

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

4. 处理请求体

request参数是通过 FFI（Foreign Function Interface）暴露的 JavaScriptRequest对象，可直接在 Python 中await其异步方法：

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))

配合本地开发服务，可用 curl 验证：

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

预期输出为Hello, Python!。

5. Web 框架的一等公民：wsgi / asgi entrypoint

入口类机制还为 Django、Flask（WSGI）和 FastAPI、Starlette（ASGI）等框架的接入铺平了道路。仓库变更日志 2026-09-02-python-workers-web-framework-support.mdx 显示：

from workers import wsgi from django.core.wsgi import get_wsgi_application app = get_wsgi_application() Default = wsgi.entrypoint(app)

该日志明确指出：wsgi.entrypoint等价于"创建一个WorkerEntrypoint类并使用wsgi.fetch方法"，也就是说——新的入口类结构正是 Python Workers 支持主流 Web 框架的基石。如果你需要更细粒度的控制，也可以手写入口类：

from workers import wsgi, WorkerEntrypoint class Default(WorkerEntrypoint): async def fetch(self, request): return await wsgi.fetch(app, request, self.env)

五、运行时原理：入口类如何被执行

理解了标志和写法之后，再看运行时层面。Python Workers 的代码由 Pyodide（编译为 WebAssembly 的 CPython）直接在 V8 isolate 中解释执行，详见 How Python Workers Work。

该文档披露的本地开发流程为：

1. 根据compatibility_date确定所需的 Pyodide 版本；
2. 依据pyproject.toml安装所需包；
3. 为 Worker 创建新的 V8 isolate 并自动注入 Pyodide；
4. 用 Pyodide 执行你的 Python 代码。

部署流程则有冷启动优化：部署时 Cloudflare 会"执行 Worker 入口模块及其顶层 import 的所有内容，然后对 Worker 的 WebAssembly 线性内存做快照"，把昂贵的初始化工作从运行时提前到部署时完成。这意味着class Default(WorkerEntrypoint)这个类的定义与导入工作，在部署阶段就被固化进快照，请求到达时直接以快照引导，显著缩短冷启动时间。

这也解释了为什么"入口类"而非"模块级函数"成为新的标准：类定义提供了清晰的模块化边界，使运行时可以在部署阶段一次性完成入口模块的解析、导入与初始化，为快照机制提供稳定且可预测的执行起点。

六、关联生态：其他兼容性标志的启示

python_no_global_handlers不是仓库中唯一的标志，理解它的同时可以参考同构案例以把握 Cloudflare 兼容性机制的通用模式。例如 enable-ctx-exports.md 定义了enable_ctx_exports（禁用名为disable_ctx_exports）标志，用于开启ctx.exportsAPI——自动为同 Worker 内的WorkerEntrypoint和 Durable Object 命名空间生成 loopback bindings。它同样遵循"enable_flag+disable_flag成对、enable_date日期门槛"的结构，且在 变更日志 2025-09-26-ctx-exports.md 中有对应的 JS 使用示例。

这套"日期自动生效 + 显式标志控制"的机制，保证了 Cloudflare 既能持续推进行为演进，又不破坏线上运行的应用——旧版本 Worker 不会被强制中断，而是通过disable_*标志获得永久的逃生通道。python_no_global_handlers正是这一治理思路在 Python Workers 上的体现。

七、总结与迁移建议

围绕python_no_global_handlers，可以总结出以下要点：

迁移建议：如果你维护的是 2025-08-14 之前创建的 Python Worker，检查代码中是否仍存在顶层on_fetch/on_scheduled函数；如有，在迁移完成前于wrangler.jsonc中加入disable_python_no_global_handlers以维持运行；随后参照本文第四节，将处理器逐一切换为Default(WorkerEntrypoint)的类方法，删除回退标志，并确保compatibility_date不早于 2025-08-14。迁移完成后，你将获得与 Workers 平台其他语言一致的结构化入口，并天然受益于部署期快照带来的冷启动优化。

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs