← Images / images / optimization

Оптимизация с помощью Workers

A привязка подключает ваш Worker на внешние ресурсы на Developer Platform, например Изображения, Бакеты R2, или Пространства имён KV.

Привязка Images позволяет оптимизировать изображения и работать с ними прямо в Worker. В отличие от Интерфейс URL, для которого изображения должны быть доступны по URL, эта привязка работает с необработанными байтами изображения. Вы можете передавать изображения из любого источника, включая Изображения, R2, fetch() ответ или тело запроса.

С помощью привязки Images вы можете:

Оптимизируйте изображение, хранящееся в Images или R2, передав байты напрямую, вместо того чтобы загружать его по публичному URL-адресу.
Измените размер изображения, наложите водяной знак, а затем измените размер полученного результата. Все эти операции выполняются в единой цепочке.
Управляйте порядком применения параметров оптимизации. При использовании URL-интерфейса параметры оптимизации применяются в фиксированном порядке.

Привязки можно настроить в панели управления Cloudflare для вашего Worker или в конфигурационном файле Wrangler в каталоге проекта.

Настройка

Привязка Images включается отдельно для каждого Worker.

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

Чтобы привязать Images к вашему Worker, добавьте следующее в конец файла конфигурации Wrangler:

{
	"images": {
		"binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
	},
}

[images]
binding = "IMAGES"

В коде своего Worker используйте env.IMAGES.input() чтобы создать объект, который может обрабатывать изображение (передаётся как ReadableStream).

Методы

Включите кэширование

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

Мы настоятельно рекомендуем включить Workers Cache чтобы повторные запросы обслуживались из кэша без повторного запуска Worker и повторного преобразования изображения. Добавьте следующее в файл конфигурации Wrangler:

{
	"cache": {
		"enabled": true,
	},
}

[cache]
enabled = true

Затем задайте Cache-Control заголовки в ответе, чтобы управлять сроком кеширования преобразованных изображений:

const response = (
	await env.IMAGES.input(stream)
		.transform({ width: 800 })
		.output({ format: "image/webp" })
).response();

return new Response(response.body, {
	headers: {
		...Object.fromEntries(response.headers),
		"Cache-Control": "public, max-age=3600, stale-while-revalidate=86400",
	},
});

const response = (
	await env.IMAGES.input(stream)
		.transform({ width: 800 })
		.output({ format: "image/webp" })
).response();

return new Response(response.body, {
	headers: {
		...Object.fromEntries(response.headers),
		"Cache-Control": "public, max-age=3600, stale-while-revalidate=86400",
	},
});

`.input(stream)`

Создаёт дескриптор оптимизации для изображения. С этого метода начинаются все операции. Принимает байты изображения размером до 20 МБ из любого источника, включая Изображения, R2, fetch() ответ или тело запроса.

Возвращает дескриптор, который можно использовать, чтобы объединить в цепочку .transform(), .draw(), а также .output() вызовы.

export default {
	async fetch(request, env) {
		const imageURL = "https://example.com/photo.jpg";

		const response = await fetch(imageURL);

		return (
			await env.IMAGES.input(response.body)
				.transform({ width: 800 })
				.output({ format: "image/webp" })
		).response();
	},
};

export default {
	async fetch(request, env) {
		const imageURL = "https://example.com/photo.jpg";

		const response = await fetch(imageURL);

		return (
			await env.IMAGES
				.input(response.body)
				.transform({ width: 800 })
				.output({ format: "image/webp" })
		).response();
	},
};

`.transform(options)`

Применяет к изображению параметры оптимизации, такие как width, height, или blur. Можно объединять несколько .transform() вызовы, чтобы управлять порядком применения параметров.

Полный список параметров см. в Возможности.

В примере ниже показано, как можно изменить размер изображения, которое хранится в Images получив байты изображения:

// Get the raw bytes of a hosted image
const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();

// Resize and transcode the image
const response = (
	await env.IMAGES.input(bytes)
		.transform({ width: 400 })
		.output({ format: "image/webp" })
).response();

return response;

// Get the raw bytes of a hosted image
const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();

// Resize and transcode the image
const response = (
  await env.IMAGES.input(bytes)
    .transform({ width: 400 })
    .output({ format: "image/webp" })
).response();

return response;

`.draw(image, options)`

Накладывает одно изображение поверх другого.

Наложение может представлять собой поток байтов изображения или другой .input() цепочку. Можно передать дочерний .transform() функцию внутри этого метода, чтобы изменить размер наложения или обработать его перед отрисовкой.

Принимает opacity, repeat, сторону (left, right, top, bottom), и composite. Полный список параметров наложения и примеры см. в Добавление наложений и водяных знаков.

`.output(options)`

Создаёт итоговое изображение с указанными параметрами вывода.

Принимает следующие параметры:

format, кодирует изображение в поддерживаемый формат, например AVIF, WebP или JPEG. Этот параметр обязателен: формат вывода по умолчанию не задан.
quality, задаёт выходной качество изображения для форматов JPEG, WebP и AVIF, задаётся фиксированным значением или уровнем воспринимаемого качества.
anim, задаёт, следует ли сохранение кадров анимации из входных файлов. Установите anim:false чтобы преобразовывать анимации в статичные изображения.

const response = (
	await env.IMAGES.input(stream)
		.transform({ rotate: 90 })
		.transform({ width: 128 })
		.transform({ blur: 20 })
		.output({ format: "image/avif" })
).response();

return response;

const response = (
	await env.IMAGES.input(stream)
		.transform({ rotate: 90 })
		.transform({ width: 128 })
		.transform({ blur: 20 })
		.output({ format: "image/avif" })
).response();

return response;

`.info(stream)`

Выводит информацию об изображении, например format, fileSize, width, а также height.

Работа с привязкой Images в локальной среде

Images API можно использовать при локальной разработке через Wrangler, интерфейс командной строки для Workers. Использование привязки Images при локальной разработке не тарифицируется.

Wrangler поддерживает две разные версии API Images:

Точная версия, поддерживающая все возможности, доступные через Images API. Это та же версия, которую Cloudflare использует по всему миру в продакшене.
Упрощённая офлайн-версия, которая поддерживает лишь часть возможностей, например изменение размера и поворот.

Чтобы протестировать упрощенную версию Images, можно выполнить wrangler dev:

npx wrangler dev

На данный момент эта версия поддерживает только width, height, rotate, а также format.

Чтобы протестировать высокоточную удаленную версию Images, можно использовать --remote флаг:

npx wrangler dev --remote

При тестировании с помощью Интеграция Workers с Vitest, по умолчанию используется упрощённая автономная версия, чтобы тесты не обращались к API Cloudflare.