Cloudflare Python Workers 完整教學 2026：Python 正式 GA、FastAPI／Django 直接跑上邊緣（pywrangler 安裝、Hello World、Workers AI、Hyperdrive 與限制陷阱一次學會）

Cloudflare Python Workers 在 2026 年 9 月 21 日正式 GA：Python 現在是 Cloudflare Workers 平台上的一級語言。你可以在邊緣節點上直接執行 FastAPI、Django、Flask，用 Python 語法呼叫 KV、D1、R2、Queues、Durable Objects 與 Workers AI，還能用 aiomysql／asyncpg 透過 Hyperdrive 連 PostgreSQL／MySQL。免費方案每天 10 萬次請求、每次 10 毫秒 CPU 時間。

這不是一個「多支援一種語言」的例行更新。Python Workers 從 2024 年進入預覽到 2026 年 9 月轉正式版，中間解的幾個問題（型別轉換、Web 框架、TCP socket、套件生態）剛好都是過去把它當玩具的原因。這篇文章從零走完一輪：安裝、部署、API、資料庫、AI，然後把限制與費用講清楚——包含哪些套件其實還跑不動。

30 秒認識 Python Workers

GA 之後，跟預覽版差在哪裡

第一代 Python Workers 有個很痛的設計：Python 物件要進到 Cloudflare 的 binding，得先手動轉成 JavaScript 物件。 例如把一個 dict 丟進 Queue，你得這樣寫：

from pyodide.ffi import to_js
import js

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

GA 版把整套型別轉換封裝進 runtime 與 Python SDK，同一件事變成：

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

差別不只是少兩行。原本那種寫法要求寫 Python 的人隨時記得底下有一層 JavaScript，Cloudflare 官方也直言這是「人類與 AI agent 都常出錯的地方」。現在 Python 端完全不用寫任何 JavaScript。

另外三個 GA 帶來的關鍵能力：

1. Web 框架原生支援。 Workers 平台本身就是 web server，不需要在 Python 裡再跑 uvicorn 或 gunicorn。Cloudflare 提供 workers.asgi 與 workers.wsgi 兩個薄轉接層，把進來的請求轉成 ASGI／WSGI 標準結構，回應再轉回去。
2. TCP socket 打通，資料庫驅動能用。 以前 Python Workers 沒有 TCP socket，asyncpg、aiomysql 這類驅動全部不能用。Cloudflare 用 Workers 的 connect API 實作了 socket 的 system call，於是驅動程式在不知情的情況下就能連上 Hyperdrive 後面的 PostgreSQL／MySQL。
3. 套件生態有了標準。 Python Workers 跑在 Wasm 沙盒裡，所有含 C/C++/Rust 原生擴充的套件都必須交叉編譯成 WebAssembly。Cloudflare 提出並推動 PEP 783（PyEmscripten） 被接受，還把 PyEmscripten 平台支援加進 cibuildwheel——這代表今後是「套件作者自己出 wasm wheel」，而不是 Cloudflare 一家一家手動編。

Step 1：安裝與建立專案

先確認本機有 uv 與 Node.js，然後在你要放專案的目錄執行：

uvx --from workers-py pywrangler init

這個指令會建立 pyproject.toml（把 workers-py 加為開發相依）與 wrangler 設定檔，並讓你從範本中挑一個起手。

如果你想要現成的範例，直接 clone 官方範例庫：

git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/hello

一個最精簡的 Python Worker 專案 pyproject.toml 長這樣：

[project]
name = "hello-python-worker"
version = "0.1.0"
description = "My first Python Worker"
requires-python = ">=3.13"
dependencies = [
    "fastapi"
]

[dependency-groups]
dev = [
    "workers-py",
    "workers-runtime-sdk"
]

pywrangler 部署時會自動把你的相依套件打包進 worker bundle，你不需要自己處理 wasm 檔案。

Step 2：四行 Hello World

Python Worker 的進入點是一個 Default 類別，繼承 WorkerEntrypoint，並實作 fetch：

from workers import WorkerEntrypoint, Response

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

對照 TypeScript 版本的 export default { async fetch(request, env, ctx) {...} }，Python 版把 handler 收進類別裡，env（環境變數與 bindings）則掛在 self.env 上。

很重要的一點：wrangler 設定檔一定要有 python_workers compatibility flag，否則不會以 Python Worker 執行：

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

本地開發與部署：

uv run pywrangler dev        # 本機 http://localhost:8787
uv run pywrangler deploy     # 部署到 <worker>.<subdomain>.workers.dev

pywrangler 支援 wrangler 的所有子命令，完整清單可以跑 uv run pywrangler --help。

Step 3：核心 API 速查

讀取 JSON 請求並回傳：

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        body = await request.json()
        name = body["name"]
        return Response(f"Hello, {name}!")

request 是透過 FFI 暴露的 JavaScript Request 物件，所以你可以直接呼叫 await request.json()、request.headers 這類 JS 端 API。

回傳 JSON：

return Response.json({"message": "Hello", "status": "ok"})

讀環境變數與 secret：

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

拆成多個模組（src/entry.py + src/hello.py）就跟一般 Python 一樣用 from hello import hello，改檔後 pywrangler dev 會自動重載。想要型別提示與自動補全，把 workers-runtime-sdk 加進相依，並執行：

uv run pywrangler types

這會依你的 bindings 與 compatibility_date 產生 Env 型別。

Step 4：把 FastAPI、Django、Flask 搬上邊緣

這是 GA 最有感的改變。你原本的 FastAPI 應用幾乎不用改：

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)

等價的寫法（想自己控制 fetch 時用）：

from workers import asgi, WorkerEntrypoint

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

Django 或 Flask 這種同步框架走 WSGI：

from workers import wsgi
from your_django_app.wsgi import app

Default = wsgi.entrypoint(app)

在傳統環境你要跑 uvicorn main:app 或 gunicorn 來處理連線與執行緒；在 Workers 上，平台本身就是 web server，負載平衡與水平擴充由 Cloudflare 網路負責，workers.asgi／workers.wsgi 只做請求與回應格式的翻譯，不另外跑伺服器行程。

Step 5：資料庫——Hyperdrive + 你熟悉的驅動

有了 socket bridge，Python 的資料庫驅動可以直接連 Hyperdrive。先在 wrangler 設定 binding：

"hyperdrive": [
  {
    "binding": "HYPERDRIVE_MYSQL",
    "id": "<你的 hyperdrive id>"
  }
]

然後用一般寫法連線：

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")
        rows = await cur.fetchall()
        await cur.close()
        conn.close()
        return Response.json({"rows": [list(r) for r in rows]})

PostgreSQL 對應 asyncpg，目前支援的驅動清單以官方 Hyperdrive 文件為準。

Step 6：在邊緣跑 AI（Workers AI、LangChain、MCP）

Python Workers 現在也支援 openai、langchain、mcp 等 AI 套件——這在過去會因為 requests／httpx 缺少底層 socket 而失效，Cloudflare 選擇上上游貢獻，讓這些 HTTP client 在 Wasm 環境改走 JavaScript 的 fetch。

搭配 Workers AI binding 與 langchain-cloudflare 的官方範例：

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 的限制比 TypeScript 版本更多，因為底層是 Wasm 沙盒。

套件相容性是最大的地雷：

• 純 Python 套件沒問題；含原生擴充的套件必須有 PyEmscripten 或 Pyodide 提供的 wasm wheel，否則裝了也跑不起來。
• HTTP client 只支援非同步的 aiohttp 與 httpx。同步的 requests 不行；真的要用，得改走 JS 的 fetch API（透過 FFI）。
• 生態還在遷移中。Cloudflare 官方請使用者在 Discord 或 GitHub 回報「缺少 wasm wheel」的套件，他們會協助跟維護者溝通。

其他容易踩到的坑：

費用：什麼時候選免費、什麼時候該付 $5

舉個實際的算式：每月 1,500 萬次請求、平均每次用 7 ms CPU，月費是 $5（訂閱）+ $1.5（請求）+ $1.5（CPU）= $8。同樣規模的自架 VPS 光是維運時間就不只這個成本。

免費方案的 10 ms CPU 是關鍵限制：純 API 路由、資料查詢轉發、輕量 AI 代理都很夠用；但要把整個 Django 應用（含模板渲染）跑在免費方案上，很可能直接撞到 CPU 上限。需要模板渲染或大量運算，請直接考慮 $5 的付費方案。

什麼時候該用、什麼時候不該用

站內延伸閱讀

• Cloudflare Tunnel 完整教學 2026：不開防火牆 port 也能把自架服務搬上網 — 如果你已經在用 Cloudflare 代理自架服務，那下一步就是把運算也搬上邊緣，這兩篇是同一條路線的前後段。
• FastAPI 完整教學 2026：從安裝、路由、Pydantic v2 到依賴注入與部署 — 本文的框架範例要用到的基礎都在這裡，先寫好本機版本再上 Workers 最省事。
• Supabase 完整教學 2026：Postgres 資料庫、Auth、Storage、Edge Functions 一次學會 — 同樣是「邊緣函式 + 託管資料庫」的組合，拿來對照費用與鎖定程度很有用。
• Docker 完整教學 2026：從安裝、Dockerfile 到安全部署 — 如果你的工作負載不適合 Workers 的資源上限，自架容器仍是更彈性的選擇。

資料來源

• Cloudflare 官方公告：https://blog.cloudflare.com/python-workers-ga/（Python Workers are now generally available，2026-09-21）
• Cloudflare 官方文件 · Python Workers：https://developers.cloudflare.com/workers/languages/python/
• Cloudflare 官方文件 · The Basics：https://developers.cloudflare.com/workers/languages/python/basics/
• Cloudflare 官方文件 · Packages：https://developers.cloudflare.com/workers/languages/python/packages/
• Cloudflare 官方文件 · FastAPI（ASGI）：https://developers.cloudflare.com/workers/languages/python/packages/fastapi/
• Cloudflare 官方文件 · Pricing：https://developers.cloudflare.com/workers/platform/pricing/
• Cloudflare 官方文件 · Limits：https://developers.cloudflare.com/workers/platform/limits/
• 官方範例庫：https://github.com/cloudflare/python-workers-examples
• PEP 783（PyEmscripten）：https://peps.python.org/pep-0783/

本文程式碼與限制數字取自 Cloudflare 官方公告與開發文件（2026 年 9 月）。套件支援範圍仍在快速變動，動手前請以官方文件最新版本為準。