跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

FastAPI

最后更新 查看 MarkdownAgent 设置

FastAPI ↗ 在 Python Workers 中受支持。

FastAPI 应用程序使用称为异步服务器网关接口(ASGI) ↗的协议。 这意味着 FastAPI 本身从不从 socket 读取或写入。ASGI 应用程序期望连接到 ASGI 服务器, 通常是 uvicorn ↗。 ASGI 服务器代表应用程序处理所有原始 socket。

Python Workers 提供一个 ASGI 服务器 ↗, 你可以直接在 Python Worker 中使用,这让你可以在 Python Workers 中使用 FastAPI。

快速入门

要在 Python Workers 中开始使用 FastAPI,请按以下步骤操作:

  1. 使用 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)
  1. 创建 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" ]
  1. 创建 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"
]
  1. 在本地运行 Worker:
uv run pywrangler dev
  1. 在另一个终端向 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:

src/worker.pypython
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

这篇文档对您有帮助吗?