← Cloudflare for Platforms / cloudflare-for-platforms / workers-for-platforms / configuration

Static Assets

Workers for Platforms позволяет развёртывать фронтенд-приложения в промышленных масштабах. Размещая статические ресурсы в глобальной сети Cloudflare, вы обеспечиваете более быструю загрузку по всему миру и устраняете необходимость во внешней инфраструктуре. Кроме того, эти статические ресурсы можно сочетать с динамической логикой в Cloudflare Workers, что даёт вашим клиентам полноценный full-stack опыт.

Размещайте и раздавайте файлы HTML, CSS, JavaScript и медиафайлы прямо из сети Cloudflare, обеспечивая быструю загрузку по всему миру. Это идеально подходит для блогов, целевых страниц и сайтов документации.

Объедините хостинг ресурсов с Cloudflare Workers, чтобы создавать динамические интерактивные приложения. Сохраняйте и получайте данные с помощью Cloudflare KV, D1 и R2 Storage, обслуживая как фронтенд-ресурсы, так и бэкенд-логику из одного Worker.

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

Ваши приложения автоматически масштабируются, чтобы выдерживать высокий трафик, и вам не нужно самостоятельно подготавливать или обслуживать инфраструктуру. Cloudflare динамически подстраивается под спрос в реальном времени.

Разверните фронтенд-ресурсы вместе с серверной логикой, всё в рамках Cloudflare Workers. Это устраняет необходимость в отдельном провайдере хостинга и упрощает процесс развёртывания.

Как правило, именно платформа отвечает за загрузку статических ресурсов от имени конечных пользователей. Обычно это выглядит так:

1. Ваш пользователь загружает файлы (HTML, CSS, изображения) через ваш интерфейс.
2. Ваша платформа взаимодействует с API Workers for Platforms, чтобы привязать статические ресурсы к скрипту User Worker.

Как только вы получите статические файлы от своих пользователей (для нового или обновлённого сайта), выполните следующие шаги, чтобы подключить файлы к соответствующему User Worker:

1. Создайте Upload Session
2. Загрузка содержимого файла
3. Разверните/обновите Worker

После выполнения этих шагов статические ресурсы User Worker станут доступны в глобальной сети Cloudflare.

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

• Путь к файлу (например, "/index.html" или "/assets/logo.png")
• Хеш (32 шестнадцатеричных символа), представляющий содержимое файла
• Размер файла в байтах

{
	"/index.html": {
		"hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
		"size": 1234
	},
	"/styles.css": {
		"hash": "36b8be012ee77df5f269b11b975611d3",
		"size": 5678
	}
}

Чтобы начать процесс загрузки, отправьте POST-запрос на Create Assets Upload Session Конечная точка API.

POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session

Параметры пути:

• namespace: Название пространства имён диспетчеризации Workers for Platforms
• script_name: Название User Worker

В теле запроса укажите объект JSON, перечисляющий для каждого пути к файлу его хеш и размер. Это помогает Cloudflare понять, какие файлы вы собираетесь загрузить, и проверить, не сохранены ли уже некоторые из них.

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME/assets-upload-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data '{
    "manifest": {
      "/index.html": {
        "hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
        "size": 1234
      },
      "/styles.css": {
        "hash": "36b8be012ee77df5f269b11b975611d3",
        "size": 5678
      }
    }
  }'

Вы можете вычислить хеш SHA-256 содержимого файла, а затем усечь его или иным способом последовательно представить в виде строки из 32 шестнадцатеричных символов. Обязательно делайте это одинаковым способом каждый раз, чтобы Cloudflare мог надёжно сопоставлять файлы между загрузками.

Если все файлы уже хранятся на Cloudflare, ответ вернёт только токен JWT. Если нужны новые или обновлённые файлы, ответ вернёт:

• jwt: Токен для загрузки (действителен 1 час), который будет использован в запросе API для загрузки содержимого файла (шаг 2).
• buckets: Массив групп хешей файлов, который показывает, какие файлы нужно загружать вместе. Недавно загруженные файлы в этих группах не появятся, поскольку они уже есть у Cloudflare.

Если ответ Upload Session API возвращает buckets, это означает, что у вас есть новые или изменённые файлы, которые нужно загрузить в Cloudflare.

Используйте Workers Assets Upload API чтобы передать исходные байты файла в формате base64 для всех отсутствующих или изменённых файлов. После загрузки Cloudflare сохранит эти файлы, чтобы их затем можно было прикрепить к User Worker.

В отличие от большинства вызовов API Cloudflare, где в заголовке Authorization используется токен API уровня аккаунта, для загрузки содержимого файлов требуется короткоживущий токен JWT, возвращённый в jwt поле assets-upload-session ответ.

Укажите его в заголовке в виде Bearer token:

Authorization: Bearer <upload-session-token>

Этот токен действителен в течение одного часа, и его нужно указывать в каждом запросе на загрузку в Workers Assets Upload API.

Файлы нужно отправить в формате multipart/form-data с содержимым в кодировке base64:

• Имя поля: хеш файла (например, 36b8be012ee77df5f269b11b975611d3)
• Значение поля: строка в кодировке Base64 с исходными байтами файла

Если в ответе вашего Upload Session указан один "bucket" с двумя хешами файлов:

"buckets": [
  [
    "08f1dfda4574284ab3c21666d1ee8c7d4",
    "36b8be012ee77df5f269b11b975611d3"
  ]
]

Вы можете загрузить оба файла в одном запросе, каждый как поле form-data:

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/assets/upload?base64=true" \
  -H "Authorization: Bearer <upload-session-token>" \
  -F "08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_OF_INDEX_HTML>" \
  -F "36b8be012ee77df5f269b11b975611d3=<BASE64_OF_STYLES_CSS>"

• <upload-session-token> это токен из ответа assets-upload-session на шаге 1
• <BASE64_OF_INDEX_HTML> это содержимое файла index.html в кодировке Base64
• <BASE64_OF_STYLES_CSS> это содержимое файла styles.css в кодировке Base64

Если у вас несколько buckets (например, [["hashA"], ["hashB"], ["hashC"]]), вам может понадобиться повторить этот процесс для каждого bucket, выполняя по одному запросу на группу bucket.

Как только все файлы из манифеста будут загружены, вернётся код состояния 201 будет возвращено, вместе с jwt поле присутствует. Этот JWT представляет собой финальный токен «completion», который можно использовать для создания развёртывания Worker с этим набором ресурсов. Данный токен завершения действителен в течение 1 часа.

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"jwt": "<completion-token>"
	}
}

<completion-token> означает, что Cloudflare успешно получил и сохранил содержимое файлов, указанное в вашем манифесте. Это значение вы будете использовать <completion-token> на шаге 3, чтобы завершить привязку этих файлов к Worker.

Теперь, когда у Cloudflare есть все нужные файлы (из предыдущих шагов загрузки), нужно подключить их к User Worker, отправив запрос PUT на API для загрузки User Worker. На этом заключительном шаге статические ресурсы связываются с User Worker с помощью completion token, полученного после загрузки содержимого файлов.

Вы также можете указать любые необязательные настройки в разделе assets.config поле для настройки способа обслуживания файлов (например, для обработки завершающих слэшей в путях HTML).

curl -X PUT \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -F 'metadata={
    "main_module": "index.js",
    "assets": {
      "jwt": "<completion-token>",
      "config": {
        "html_handling": "auto-trailing-slash"
      }
    },
    "compatibility_date": "2025-01-24"
  };type=application/json' \
  -F 'index.js=@/path/to/index.js;type=application/javascript'

• "jwt": "<completion-token>" связывает только что загруженные файлы с Worker
• Указывать "html_handling" (или другие поля внутри "config") необязательно, но это позволяет настроить, как обслуживаются статические файлы
• Если код Worker пользователя не изменился, можно не указывать файл с кодом или повторно загрузить тот же index.js

Как только этот запрос PUT завершится успешно, файлы станут доступны на User Worker. Запросы, направленные на этот Worker, будут обслуживать новые или обновлённые статические ресурсы.

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

Создайте или обновите свой конфигурационный файл Wrangler чтобы указать, где Wrangler должен искать статические файлы:

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

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

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

• directory: Локальная папка, содержащая ваши статические файлы (например, ./public).
• binding: Имя binding, которое используется в коде вашего Worker для обращения к этим ресурсам.

Поместите свои статические файлы (HTML, CSS, изображения и т. д.) в указанный каталог (в этом примере ./public). Wrangler обнаружит эти файлы и включит их в сборку при публикации вашего Worker.

Если вам нужно ссылаться на эти файлы в скрипте Worker, чтобы отдавать их динамически, можно использовать ASSETS binding следующим образом:

export default {
	async fetch(request, env, ctx) {
		return env.ASSETS.fetch(request);
	},
};

Запустите Wrangler, чтобы опубликовать код своего Worker и статические ресурсы:

npx wrangler deploy --name <USER_WORKER_NAME> --dispatch-namespace <NAMESPACE_NAME>

Wrangler автоматически определит статические файлы, упакует их и загрузит в Cloudflare вместе с кодом вашего Worker.