← Cloudflare Workers / workers

Static Assets

Статические ресурсы (HTML, CSS, изображения и другие файлы) можно загрузить как часть Worker, а Cloudflare возьмёт на себя их кэширование и раздачу в браузеры.

Начало из CLI - Создайте каркас React SPA с API Worker и используйте Cloudflare Vite plugin.

npm create cloudflare@latest -- my-react-app --framework=react

Или просто разверните на Cloudflare

Подробнее о фреймворках, поддерживаемых в Workers.

Когда вы развёртываете проект, Cloudflare разворачивает код Worker и статические ресурсы одной операцией. Такое развёртывание работает как единое целое «unit» в сети Cloudflare, объединяя хостинг статических файлов, пользовательскую логику и глобальное кэширование.

каталог assets указанный в вашем конфигурационный файл Wrangler занимает центральное место в этом подходе. При развёртывании Wrangler автоматически загружает файлы из этой директории в инфраструктуру Cloudflare. После развёртывания запросы к этим ресурсам эффективно направляются в локации, ближайшие к вашим пользователям.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-spa",
  "main": "src/index.js",
  // Set this to today's date
  "compatibility_date": "2026-08-28",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS"
  }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-spa"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-08-28"

[assets]
directory = "./dist"
binding = "ASSETS"

Добавив привязка assets, вы можете напрямую получать и отдавать статические ресурсы прямо в коде Worker.

// index.js

export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (url.pathname.startsWith("/api/")) {
			return new Response(JSON.stringify({ name: "Cloudflare" }), {
				headers: { "Content-Type": "application/json" },
			});
		}

		return env.ASSETS.fetch(request);
	},
};

from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse

class Default(WorkerEntrypoint):
	async def fetch(self, request):
		# Example of serving static assets
		url = urlparse(request.url)
		if url.path.startswith("/api/):
			return Response.json({"name": "Cloudflare"})

		return await self.env.ASSETS.fetch(request)

По умолчанию, если запрошенный URL-адрес соответствует файлу в каталоге статических ресурсов, этот файл отдаётся напрямую, без вызова кода Worker. Если подходящий ресурс не найден и присутствует скрипт Worker, запрос обрабатывает Worker. Worker может вернуть ответ или снова передать обработку статическим ресурсам с помощью привязка assets (например, env.ASSETS.fetch(request)). Если скрипт Worker отсутствует, 404 Not Found возвращается ответ.

Поведение по умолчанию для запросов, не соответствующих статическому ресурсу, можно изменить, задав not_found_handling параметр в разделе assets в конфигурационном файле Wrangler:

• not_found_handling = "single-page-application": Настраивает приложение так, чтобы оно возвращало 200 OK ответ с index.html для запросов, не соответствующих ни одному статическому ресурсу. Используйте этот вариант, если у вас одностраничное приложение (SPA). Рекомендуем сочетать его с выборочной маршрутизацией через run_worker_first для расширенное управление маршрутизацией.
• not_found_handling = "404-page": Настраивает приложение так, чтобы оно возвращало 404 Not Found ответ с ближайшим 404.html для запросов, не соответствующих ни одному статическому ресурсу.

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "single-page-application"
  }
}

[assets]
directory = "./dist"
not_found_handling = "single-page-application"

Если вы хотите, чтобы код Worker выполнялся перед раздачей ресурсов, вы можете использовать run_worker_first параметр. Его можно задать как true чтобы вызывать скрипт Worker для всех запросов, либо задан как массив шаблонов маршрутов для выборочной маршрутизации с приоритетом скрипта Worker:

Вызов скрипта Worker для определённых путей:

{
	"name": "my-spa-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./src/index.ts",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "single-page-application",
		"binding": "ASSETS",
		"run_worker_first": ["/api/*", "!/api/docs/*"]
	}
}

name = "my-spa-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./src/index.ts"

[assets]
directory = "./dist/"
not_found_handling = "single-page-application"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]

Более сложный подход описан в SPA-оболочки с bootstrap-данными, который использует HTMLRewriter, чтобы встроить заранее полученные данные API в поток HTML.

Cloudflare обеспечивает автоматическое кэширование статических ресурсов по всей своей сети, гарантируя быструю доставку пользователям по всему миру. При запросе статического ресурса он автоматически кэшируется для последующих запросов.

• Первый запрос: При первом запросе ресурса он извлекается из хранилища и кешируется в ближайшей точке присутствия Cloudflare.

• Последующие запросы: Если запрос на тот же ресурс поступает в дата-центр, где этот ресурс ещё не закеширован, функция Cloudflare система многоуровневого кэширования позволяет получать данные из ближайшего кеша, а не обращаться заново к хранилищу. Это повышает коэффициент попаданий в кеш, снижает задержку и сокращает лишние обращения к источнику.