INTEGRITY Документация

← Cloudflare Workers / workers

Локальная разработка

Код Worker можно собирать, запускать и тестировать на локальной машине перед развёртыванием в сети Cloudflare. Это становится возможным благодаря Miniflare, симулятор, который выполняет код вашего Worker с использованием той же среды выполнения (runtime), что и в продакшене, workerd ↗.

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

Основные концепции

Выполнение Worker и привязки

При разработке Workers важно понимать два разных понятия:

Запуск локального сервера разработки

Локальный сервер разработки можно запустить с помощью:

  1. CLI Cloudflare Workers Wrangler, с помощью встроенного wrangler dev команда.
npx wrangler dev
  1. Vite ↗, с помощью Cloudflare Vite plugin.
npx vite dev

И Wrangler, и плагин Cloudflare для Vite используют Miniflare под капотом и разрабатываются и поддерживаются командой Cloudflare. Рекомендации по выбору между Wrangler и Vite см. в нашем руководстве Выбор между Wrangler и Vite.

Значения по умолчанию

По умолчанию запуск wrangler dev / vite dev (при использовании Плагин Vite) означает, что:

Привязки при локальной разработке

Bindings это интерфейсы, которые позволяют вашему Worker взаимодействовать с различными ресурсами Cloudflare (например, Пространства имён KV, Бакеты R2, Базы данных D1, Queues, Durable Objects, и т. д.). В коде вашего Worker к ним можно обратиться через env объект (например, env.MY_KV).

Во время локальной разработки код Worker обращается к этим привязкам с помощью тех же самых вызовов API (например, env.MY_KV.put()) так же, как и в развёрнутом окружении. Изначально эти локальные ресурсы пусты, но вы можете заполнить их данными, как описано в Добавление локальных данных.

Remote Bindings

Remote Bindings это bindings, настроенные на подключение к развёрнутому удалённому ресурсу во время локальной разработки вместо этого локально симулируемого ресурса. Remote bindings поддерживаются Wrangler, Cloudflare Vite plugin, и @cloudflare/vitest-plugin пакет. Настроить удалённые привязки можно, задав remote: true в определении привязки.

Пример конфигурации

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",

	"r2_buckets": [
		{
			"bucket_name": "screenshots-bucket",
			"binding": "screenshots_bucket",
			"remote": true,
		},
	],
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"

[[r2_buckets]]
bucket_name = "screenshots-bucket"
binding = "screenshots_bucket"
remote = true

Если настроены remote bindings, ваш Worker все равно выполняется локально, изменяются только базовые ресурсы, к которым подключаются ваши биндинги. Для всех биндингов, отмеченных remote: true, Miniflare будет направлять свои операции (такие как env.MY_KV.put()) к развёрнутому ресурсу. Все остальные привязки, для которых явно не настроено remote: true продолжают использовать локальные симуляции по умолчанию.

Интеграция со средами

Remote Bindings хорошо работают вместе с Окружения Workers. Чтобы защитить продакшен-данные, вы можете создать окружение для разработки или staging и указать другие ресурсы в Конфигурация Wrangler чем вы использовали бы для продакшена.

Например:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",

	"env": {
		"production": {
			"r2_buckets": [
				{
					"bucket_name": "screenshots-bucket",
					"binding": "screenshots_bucket",
				},
			],
		},
		"staging": {
			"r2_buckets": [
				{
					"bucket_name": "preview-screenshots-bucket",
					"binding": "screenshots_bucket",
					"remote": true,
				},
			],
		},
	},
}
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"

[[env.production.r2_buckets]]
bucket_name = "screenshots-bucket"
binding = "screenshots_bucket"

[[env.staging.r2_buckets]]
bucket_name = "preview-screenshots-bucket"
binding = "screenshots_bucket"
remote = true

Выполнение wrangler dev -e staging (или CLOUDFLARE_ENV=staging vite dev) с приведённой выше конфигурацией означает, что:

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

Для следующих привязок рекомендуется иметь remote: true в конфигурации Wrangler:

Browser Run:

Взаимодействие с реальным headless-браузером для рендеринга. Локальной симуляции для Browser Run пока не существует.

{
	"browser": {
		"binding": "MY_BROWSER",
		"remote": true
	},
}
[browser]
binding = "MY_BROWSER"
remote = true

Workers AI:

Чтобы использовать реальные AI-модели, развёрнутые в сети Cloudflare, для инференса. Локальная симуляция для Workers AI пока не поддерживается.

{
	"ai": {
		"binding": "AI",
		"remote": true
	},
}
[ai]
binding = "AI"
remote = true

Vectorize:

Чтобы подключиться к продакшен-индексам Vectorize для точного векторного поиска и операций сравнения схожести. В настоящее время локальная симуляция для Vectorize отсутствует.

{
	"vectorize": [
		{
			"binding": "MY_VECTORIZE_INDEX",
			"index_name": "my-prod-index",
			"remote": true
		}
	],
}
[[vectorize]]
binding = "MY_VECTORIZE_INDEX"
index_name = "my-prod-index"
remote = true

mTLS:

Чтобы убедиться, что обмен сертификатами и процесс проверки работают как ожидается. Локальная симуляция для привязок mTLS пока не поддерживается.

{
	"mtls_certificates": [
		{
			"binding": "MY_CLIENT_CERT_FETCHER",
			"certificate_id": "<YOUR_UPLOADED_CERT_ID>",
			"remote": true
			}
	]
}
[[mtls_certificates]]
binding = "MY_CLIENT_CERT_FETCHER"
certificate_id = "<YOUR_UPLOADED_CERT_ID>"
remote = true

Изображения:

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

{
	"images": {
		"binding": "IMAGES" ,
		"remote": true
	}
}
[images]
binding = "IMAGES"
remote = true

Dispatch Namespaces:

Пользователи Workers for Platforms могут настраивать remote: true в определениях привязок пространств имён диспетчеризации:

{
	"dispatch_namespaces": [
		{
			"binding": "DISPATCH_NAMESPACE",
			"namespace": "testing",
			"remote":true
		}
	]
}
[[dispatch_namespaces]]
binding = "DISPATCH_NAMESPACE"
namespace = "testing"
remote = true

Это позволяет запускать ваш Worker динамической диспетчеризации локально, подключив его к вашей удалённой привязке dispatch namespace. Это позволяет проверять изменения в основной логике диспетчеризации на реальных, уже развёрнутых пользовательские Workers.

Неподдерживаемые удалённые bindings

Некоторые привязки не поддерживаются для удаленных подключений (то есть с remote: true) при локальной разработке. Они всегда будут использовать локальные симуляции или локальные значения.

Если remote: true указан в конфигурации Wrangler для любого из следующих неподдерживаемых типов привязок, Cloudflare выдаст ошибку. См. все поддерживаемые и неподдерживаемые привязки для удалённых привязок.

Использование удалённых ресурсов с Durable Objects и Workflows

Хотя bindings для Durable Object и Workflow пока не могут быть remote, вы можете использовать их при локальной разработке, чтобы они взаимодействовали с удаленными ресурсами.

Для этого рекомендуются два подхода:

Важные замечания

Подключение к Workers, защищённым Access

Если ваш Worker защищён Cloudflare Access, Wrangler должен пройти аутентификацию через Access при подключении к удаленным привязкам. Это применяется независимо от того, защищает ли Access сам Worker, все Workers в аккаунте или workers.dev хост, Custom Domain либо другой хост или путь, который направляет трафик на Worker.

Пройти аутентификацию в Access можно двумя способами:

Чтобы настроить аутентификацию с помощью Service Token:

  1. Создайте сервисный токен.

    В панели управления Cloudflare перейдите в Zero Trust > Доступ > Service Auth > Service Tokens и создайте новый токен. См. Service tokens для полного описания. Вам будут показаны Client ID и Client Secret: сохраните их в надёжном месте, так как секрет больше не будет показан.

  2. Добавьте политику Service Auth в приложение Access, защищающее ваш Worker.

    Откройте существующее Access-приложение, которое уже защищает Worker или хост, используемый для удаленных привязок, и подключите к нему новую политику:

    • Действие: Service Auth
    • Включить: Созданный вами токен службы или "Any Access Service Token", если нужно разрешить доступ к Worker любому токену службы.

  3. Предоставьте учётные данные Wrangler.

    Задайте CLOUDFLARE_ACCESS_CLIENT_ID и CLOUDFLARE_ACCESS_CLIENT_SECRET системные переменные окружения в окружении, в котором запускается Wrangler:

    export CLOUDFLARE_ACCESS_CLIENT_ID=<CLIENT_ID>
export CLOUDFLARE_ACCESS_CLIENT_SECRET=<CLIENT_SECRET>

    В CI храните значения как секреты и передавайте их в виде переменных окружения на шаг, где запускается Wrangler.

API

Wrangler предоставляет программные утилиты, которые помогают разработчикам инструментов поддерживать удалённые подключения через привязки при выполнении кода Workers с помощью Miniflare.

Основные API:

startRemoteProxySession

Эта функция запускает прокси-сессию для заданного набора привязок (bindings). Она принимает параметры для управления поведением сессии, включая auth параметр с ID вашего аккаунта Cloudflare и API токеном для доступа к удалённым привязкам.

Возвращает объект, содержащий:

unstable_convertConfigBindingsToStartWorkerBindings

unstable_readConfig утилита возвращает Unstable_Config объект, который включает определения привязок (bindings), указанных в конфигурационном файле. Однако эти определения привязок напрямую не совместимы с startRemoteProxySession. Тем не менее бывает удобно читать объявления привязок с помощью unstable_readConfig и затем передайте их в startRemoteProxySession, поэтому для этого wrangler предоставляет unstable_convertConfigBindingsToStartWorkerBindings это простая утилита для преобразования привязок в Unstable_Config объект в структуру, которую можно передать в startRemoteProxySession.

maybeStartOrUpdateRemoteProxySession

Эта обертка упрощает управление сессиями прокси. Она принимает:

Возвращает объект с сведениями о сеансе прокси, если он запущен или обновлён, либо null если сеанс прокси не нужен.

Функция:

Пример

Ниже приведён базовый пример использования Miniflare с maybeStartOrUpdateRemoteProxySession чтобы обеспечить локальную сессию разработки с удаленными привязками. В этом примере используется одна жёстко заданная привязка KV.

import { Miniflare, MiniflareOptions } from "miniflare";
import { maybeStartOrUpdateRemoteProxySession } from "wrangler";

let mf;

let remoteProxySessionDetails = null;

async function startOrUpdateDevSession() {
	remoteProxySessionDetails = await maybeStartOrUpdateRemoteProxySession(
		{
			bindings: {
				MY_KV: {
					type: "kv_namespace",
					id: "kv-id",
					remote: true,
				},
			},
		},
		remoteProxySessionDetails,
	);

	const miniflareOptions = {
		scriptPath: "./worker.js",
		kvNamespaces: {
			MY_KV: {
				id: "kv-id",
				remoteProxyConnectionString:
					remoteProxySessionDetails?.session.remoteProxyConnectionString,
			},
		},
	};

	if (!mf) {
		mf = new Miniflare(miniflareOptions);
	} else {
		mf.setOptions(miniflareOptions);
	}
}

// ... tool logic that invokes `startOrUpdateDevSession()` ...

// ... once the dev session is no longer needed run
// `remoteProxySessionDetails?.session.dispose()`
import { Miniflare, MiniflareOptions } from "miniflare";
import { maybeStartOrUpdateRemoteProxySession } from "wrangler";

let mf: Miniflare | null;

let remoteProxySessionDetails: Awaited<
	ReturnType<typeof maybeStartOrUpdateRemoteProxySession>
> | null = null;

async function startOrUpdateDevSession() {
	remoteProxySessionDetails = await maybeStartOrUpdateRemoteProxySession(
		{
			bindings: {
				MY_KV: {
					type: "kv_namespace",
					id: "kv-id",
					remote: true,
				},
			},
		},
		remoteProxySessionDetails,
	);

	const miniflareOptions: MiniflareOptions = {
		scriptPath: "./worker.js",
		kvNamespaces: {
			MY_KV: {
				id: "kv-id",
				remoteProxyConnectionString:
					remoteProxySessionDetails?.session.remoteProxyConnectionString,
			},
		},
	};

	if (!mf) {
		mf = new Miniflare(miniflareOptions);
	} else {
		mf.setOptions(miniflareOptions);
	}
}

// ... tool logic that invokes `startOrUpdateDevSession()` ...

// ... once the dev session is no longer needed run
// `remoteProxySessionDetails?.session.dispose()`

wrangler dev --remote (устаревшее)

Помимо локальной разработки на базе Miniflare, Wrangler также предлагает полностью удалённый режим разработки через wrangler dev --remote. Удалённая разработка не поддерживается в плагине Vite.

npx wrangler dev --remote

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

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

Когда использовать удалённую разработку

Особенности

Ограничения