← Cloudflare Workers / workers / languages / python / packages

FastAPI

Пакет FastAPI поддерживается в Python Workers.

Приложения FastAPI используют протокол под названием Asynchronous Server Gateway Interface (ASGI) ↗. Это означает, что FastAPI сам никогда не читает из сокета и не пишет в него. ASGI приложение рассчитано на подключение к ASGI серверу, обычно uvicorn ↗. ASGI сервер берёт на себя обработку всех низкоуровневых сокетов от имени приложения.

Python Workers предоставляют ASGI-сервер ↗ который можно использовать прямо в вашем Python Worker и который позволяет использовать FastAPI в Python Workers.

Чтобы начать работу с FastAPI в Python Workers, выполните следующие шаги:

2. Создайте src/main.py файл вашим приложением FastAPI:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

from workers import asgi
Default = asgi.entrypoint(app)

3. Создайте wrangler.jsonc файл, чтобы настроить ваш Worker:

{
	"name": "my-fastapi-app",
	"main": "src/main.py",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": ["python_workers"],
}

name = "my-fastapi-app"
main = "src/main.py"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "python_workers" ]

4. Создайте 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"
]

5. Запустите ваш Worker локально:

uv run pywrangler dev

Одностраничное приложение (SPA) или любой статический фронтенд можно обслуживать вместе с бэкендом FastAPI с помощью Workers Static Assets.

Это эквивалентно встроенному в FastAPI app.frontend() ↗ метод, который обслуживает статическую директорию сборки как маршруты с низким приоритетом, чтобы операции по путям API проверялись первыми. Разница в том, где хранятся файлы: app.frontend() считывает файлы из локальной файловой системы, тогда как в Workers статические ресурсы отдаются из глобально распределенного хранилища ресурсов Cloudflare через ASSETS привязку. Это значит, что файлы фронтенда не упаковываются внутрь самого Worker, благодаря чему бандл остаётся небольшим.

Поместите результат сборки фронтенда (например, файлы HTML, CSS и JavaScript) в каталог, например ./public/. Затем настройте файл Wrangler, добавив assets блок, который включает binding и задаёт run_worker_first к true. Это гарантирует, что каждый запрос сначала попадает в ваш FastAPI Worker, поэтому маршруты API имеют приоритет над статическими файлами.

Добавьте catch-all маршрут в конце приложения FastAPI, который проксирует несовпавшие запросы в привязку assets:

{
	"name": "my-fastapi-app",
	"main": "src/worker.py",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"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-08-28"
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()
    headers = dict(resp.headers)
    return Response(content=body, status_code=resp.status, headers=headers)

Этот worker можно запустить локально с помощью uv run pywrangler dev.

При такой настройке запрос к /api/hello обрабатывается FastAPI, а запрос к /index.html или любой другой путь обслуживается из ./public/ каталог через привязку assets.

Подробнее о настройке статических файлов см. в документация 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