← Cloudflare Workers / workers / static-assets

Конфигурация и Bindings

Для настройки Worker со статическими ресурсами необходимо указать каталог и, при необходимости, привязка assets, в файле Wrangler вашего Worker. привязка assets позволяет динамически получать ресурсы (assets) прямо из скрипта Worker (например, env.ASSETS.fetch()), подобно тому, как вы могли бы сделать fetch() вызов с Service binding.

В каждом Worker можно настроить только одну коллекцию статических файлов.

Каталог статических ресурсов для раздачи. Для многих фреймворков это ./public/, ./dist/, или ./build/ папка.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"assets": {
		"directory": "./public/",
	},
}

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

[assets]
directory = "./public/"

Иногда в каталоге ресурсов оказываются файлы, которые не нужно загружать.

В этом случае создайте .assetsignore файл в корне каталога с ресурсами. Этот файл имеет тот же формат, что и .gitignore.

Wrangler не будет загружать файлы ресурсов, соответствующие строкам в этом файле.

Пример

Вы выполняете миграцию с проекта Pages, в котором каталог assets, это dist. Вы не хотите, чтобы серверный код Worker или файлы конфигурации Pages загружались как публичные клиентские ресурсы. Добавьте следующее .assetsignore файле:

_worker.js
_redirects
_headers

Теперь Wrangler не будет загружать эти файлы как клиентские ресурсы при развертывании Worker.

Управляет тем, следует ли вызывать скрипт Worker независимо от запроса, который иначе соответствовал бы ресурсу. run_worker_first = false (по умолчанию) будет отдавать любой статический ресурс, соответствующий запросу, тогда как run_worker_first = true безусловно вызвать скрипт Worker.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "src/index.ts",
	// The following configuration unconditionally invokes the Worker script at
	// `src/index.ts`, which can programmatically fetch assets via the ASSETS binding
	"assets": {
		"directory": "./public/",
		"binding": "ASSETS",
		"run_worker_first": true,
	},
}

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

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

Также можно указать run_worker_first в виде массива шаблонов маршрутов, чтобы скрипт Worker выполнялся первым только для определённых маршрутов.

Массив поддерживает glob-шаблоны с * для глубокого сопоставления и отрицательных шаблонов с ! префикс.

Отрицательные шаблоны имеют приоритет над неотрицательными. Worker запускается только тогда, когда совпадает неотрицательный шаблон и не совпадает ни один отрицательный.

Порядок, в котором перечислены шаблоны, не имеет значения.

run_worker_first часто используется вместе с not_found_handling = "single-page-application" настройка:

{
	"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/*" ]

В этой конфигурации запросы к /api/* маршруты сначала вызовут скрипт Worker, за исключением /api/docs/* который будет использовать стандартное поведение маршрутизации asset-first.

Типичные способы использования run_worker_first включают проверки аутентификации, A/B тестирование и внедрение начальных данных в оболочку SPA.

Настройка необязательного привязка даёт доступ к коллекции ресурсов изнутри скрипта вашего Worker.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"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-worker"
main = "./src/index.js"
# Set this to today's date
compatibility_date = "2026-08-28"

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

В примере выше ресурсы будут доступны через env.ASSETS.

Параметры

• request: Request | URL | string Передайте Объект Request, объект URL или строку URL. Запросы, выполненные этим методом, имеют html_handling и not_found_handling применённую к ним конфигурацию.

Ответ

• Promise<Response> Возвращает ответ со статическим ресурсом для указанного запроса.

Пример

Ваш динамический код может создавать новые запросы или перенаправлять входящие запросы к статическим ресурсам проекта с помощью привязки assets. Например, env.ASSETS.fetch(request), env.ASSETS.fetch(new URL('https://assets.local/my-file')) или env.ASSETS.fetch('https://assets.local/my-file'). Имя хоста, используемое в URL (например, assets.local) не имеет значения: подойдёт любое корректное имя хоста. Для сопоставления ресурсов используется только путь URL.

Рассмотрим пример, в котором Worker настроен на возврат ответа для всех запросов, направленных на /api/. В противном случае скрипт Worker передаст входящий запрос привязке ресурсов. В этом случае, поскольку скрипт Worker вызывается только тогда, когда запрошенный маршрут не совпал ни с одним статическим ресурсом, это всегда даёт not_found_handling поведение.

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Passes the incoming request through to the assets binding.
		// No asset matched this request, so this will evaluate `not_found_handling` behavior.
		return env.ASSETS.fetch(request);
	},
};

interface Env {
	ASSETS: Fetcher;
}

export default {
	async fetch(request, env): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Passes the incoming request through to the assets binding.
		// No asset matched this request, so this will evaluate `not_found_handling` behavior.
		return env.ASSETS.fetch(request);
	},
} satisfies ExportedHandler<Env>;

Различные параметры настройки маршрутизации статических файлов см. в Маршрутизация.

Smart Placement можно использовать, чтобы разместить код Worker ближе к вашей серверной инфраструктуре. Smart Placement действует только в том случае, если указан main, указывающий на код вашего Worker.

Если вы хотите запустить Код Worker выполняется раньше ресурсов задав run_worker_first=true, все запросы должны сначала пройти через ваш Smart-Placed Worker. В результате вы можете столкнуться с повышенной задержкой при запросах ресурсов.

Используйте Smart Placement с run_worker_first=true когда вам нужно интегрироваться с другими бэкенд сервисами, аутентифицировать запросы перед отдачей ресурсов или изменять ресурсы перед их отдачей.

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

Включение Smart Placement с run_worker_first=false (или если его не указывать) позволяет обслуживать ресурсы максимально близко к вашим пользователям, но переносит выполнение логики Worker туда, где оно наиболее эффективно (например, ближе к базе данных).

Используйте Smart Placement с run_worker_first=false (или если его не указывать), если в приоритете быстрая доставка ресурсов.

Это не повлияет на поведение маршрутизации по умолчанию.