FastAPI ↗ 在 Python Workers 中受支持。
FastAPI 应用程序使用称为异步服务器网关接口(ASGI) ↗的协议。 这意味着 FastAPI 本身从不从 socket 读取或写入。ASGI 应用程序期望连接到 ASGI 服务器, 通常是 uvicorn ↗。 ASGI 服务器代表应用程序处理所有原始 socket。
Python Workers 提供一个 ASGI 服务器 ↗, 你可以直接在 Python Worker 中使用,这让你可以在 Python Workers 中使用 FastAPI。
要在 Python Workers 中开始使用 FastAPI,请按以下步骤操作:
- 使用 FastAPI 应用程序创建
src/main.py文件:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
from workers import asgi
Default = asgi.entrypoint(app)- 创建
wrangler.jsonc文件以配置 Worker:
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "my-fastapi-app",
"main": "src/main.py",
// Set this to today's date
"compatibility_date": "2026-11-20",
"compatibility_flags": ["python_workers"],
}"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-fastapi-app"
main = "src/main.py"
# Set this to today's date
compatibility_date = "2026-11-20"
compatibility_flags = [ "python_workers" ]- 创建
pyproject.toml文件以管理依赖:
[project]
name = "my-fastapi-app"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"fastapi",
]
[dependency-groups]
dev = [
"workers-py",
"workers-runtime-sdk"
]- 在本地运行 Worker:
uv run pywrangler dev-
在另一个终端向 Worker 发送请求:
curl http://localhost:8787/Worker 返回:
{"Hello": "World"}
你可以使用 Workers Static Assets 与 FastAPI 后端一起提供任何静态前端。
这相当于 FastAPI 原生的 app.frontend() ↗ 方法,该方法将静态构建目录作为低优先级路由提供,以便先检查 API 路径操作。区别在于文件存放位置:app.frontend() 从本地文件系统读取文件,而在 Workers 上,静态资源通过 ASSETS 绑定从 Cloudflare 全球分布的资源存储提供。这意味着前端文件不会打包进 Worker 本身,从而保持包体积较小。
将前端构建输出(例如 HTML、CSS 和 JavaScript 文件)
放在例如 ./public/ 的目录中。然后在 Wrangler 文件中配置包含
binding 并将 run_worker_first 设为 true 的 assets 块。
这确保每个请求先到达 FastAPI Worker,因此 API 路由
优先于静态文件。
在 FastAPI 应用末尾添加兜底路由,将未匹配的请求代理到 assets 绑定:
{
"name": "my-fastapi-app",
"main": "src/worker.py",
// Set this to today's date
"compatibility_date": "2026-11-20",
"compatibility_flags": ["python_workers"],
"assets": {
"directory": "./public/",
"binding": "ASSETS",
"run_worker_first": true
}
}name = "my-fastapi-app"
main = "src/worker.py"
# Set this to today's date
compatibility_date = "2026-11-20"
compatibility_flags = [ "python_workers" ]
[assets]
directory = "./public/"
binding = "ASSETS"
run_worker_first = true请务必创建 pyproject.toml 文件以管理依赖:
[project]
name = "my-fastapi-app"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"fastapi",
]
[dependency-groups]
dev = [
"workers-py",
"workers-runtime-sdk"
]然后编写 Worker:
from fastapi import FastAPI, Request
from fastapi.responses import Response
from workers import asgi
app = FastAPI()
Default = asgi.entrypoint(app)
@app.get("/api/hello")
async def api_hello():
return {"message": "Hello from the API"}
# Catch-all: proxy everything else to Workers Static Assets.
# This is the Workers equivalent of app.frontend("/", directory="dist").
@app.get("/{path:path}")
async def frontend(path: str, request: Request):
env = request.scope["env"]
asset_url = f"https://assets.local/{path}"
resp = await env.ASSETS.fetch(asset_url)
body = await resp.bytes()
return Response(content=body, status_code=resp.status, headers=resp.headers)你可以使用 uv run pywrangler dev 在本地运行此 Worker。
使用此设置时,对 /api/hello 的请求由 FastAPI 处理,而对 /index.html 或任何其他路径的请求则通过 assets 绑定从 ./public/ 目录提供。
有关配置静态资源的更多信息,请参阅 Workers Static Assets 文档。
克隆 cloudflare/python-workers-examples 仓库并运行其中的 FastAPI 示例:
git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/fastapi
uv run pywrangler dev