← Cloudflare Pages / pages / functions

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

Pages Functions можно настроить двумя способами: либо через Панель управления Cloudflare ↗ или файл конфигурации Wrangler, файл, который используется для настройки процесса разработки и развертывания Workers и Pages Functions.

Эта страница служит справочником по настройке проекта Pages через файл конфигурации Wrangler.

При использовании конфигурационного файла Wrangler следует относиться к этому файлу как к источник достоверных данных для конфигурации вашего проекта Pages.

Использование файла конфигурации Wrangler для настройки проекта Pages позволяет:

• Сохраните файл конфигурации в системе контроля версий: Храните конфигурацию в репозитории вместе с остальным кодом.
• Измените конфигурацию в вашем редакторе кода: Избавляет от необходимости переключаться между интерфейсами.
• Настройте конфигурацию, общую для всех окружений: Определите конфигурацию, например привязки для локальной разработки, preview и production в одном файле.
• Обеспечьте более строгий контроль доступа: Используя файл конфигурации в репозитории проекта, вы можете контролировать, у кого есть доступ для внесения изменений, не предоставляя доступ к панели управления Cloudflare.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-app",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "northwind-demo",
			"database_id": "<DATABASE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-app"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[[d1_databases]]
binding = "DB"
database_name = "northwind-demo"
database_id = "<DATABASE_ID>"

[vars]
API_KEY = "1234567asdf"

Для настройки Pages Functions через файл конфигурации Wrangler требуется Система сборки V2 или более позднюю версию. Чтобы обновиться с V1, см. Инструкции по переходу на систему сборки V2.

Для использования файла конфигурации Wrangler в настройках проекта Pages требуется Wrangler версии 3.45.0 или выше. Чтобы проверить версию Wrangler, обновить или установить его, обратитесь к Установка/Обновление Wrangler.

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

До того как в файле конфигурации Wrangler появилась возможность задавать настройки preview- и production-окружений, с его помощью также определялось, какой привязки должен быть доступен вашему проекту Pages при локальной разработке.

Если вы уже использовали конфигурационный файл Wrangler для локальной разработки, в вашем проекте Pages может уже быть файл, похожий на этот:

{
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	]
}

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

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

1. Добавьте pages_build_output_dir ключ, указав соответствующее значение каталог вывода сборки (например, pages_build_output_dir = "./dist".)
2. Перед развертыванием внимательно проверьте текущую конфигурацию Wrangler, чтобы убедиться, что она соответствует нужной конфигурации проекта.

Если вы добавите pages_build_output_dir ключ в конфигурационный файл Wrangler и развернуть проект Pages, Pages будет использовать конфигурацию, заданную для локальной разработки, что почти наверняка не подходит для продакшена. Не выполняйте развёртывание, пока не убедитесь, что конфигурационный файл Wrangler готов к использованию в продакшене.

Файл Wrangler можно и дальше использовать для локальной разработки, не перенося его для использования в продакшене, если не добавлять pages_build_output_dir ключ. Если вы не добавите pages_build_output_dir ключ и выполните wrangler pages deploy, вы увидите предупреждение о том, что отсутствуют некоторые поля и что файл по-прежнему будет использоваться только для локальной разработки.

Если у вас уже есть проект Pages с конфигурацией, настроенной через дашборд Cloudflare, и в проекте еще нет файла Wrangler, выполните wrangler pages download config команду в каталоге вашего проекта Pages. wrangler pages download config загрузит текущую конфигурацию из дашборда Cloudflare и создаст корректный файл Wrangler в директории вашего проекта Pages.

npx wrangler pages download config <PROJECT_NAME>

yarn wrangler pages download config <PROJECT_NAME>

pnpm wrangler pages download config <PROJECT_NAME>

Ознакомьтесь со сгенерированным файлом Wrangler. Чтобы начать использовать файл конфигурации Wrangler для настройки вашего проекта Pages, создайте новое развертывание через Интеграция с Git или Direct Upload.

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

Если вы скачиваете конфигурационный файл Wrangler из проекта, настроенного на "Latest", с помощью wrangler pages download ваш файл конфигурации Wrangler будет содержать последнюю доступную на момент загрузки дату совместимости. Wrangler не поддерживает функцию «Latest», как это делает дашборд. При использовании файла конфигурации Wrangler даты совместимости необходимо задавать явно.

См. это руководство чтобы узнать, что такое compatibility dates и как они работают.

Если вы использовали Workers, возможно, вы уже знакомы с конфигурационный файл Wrangler. При использовании этого файла в проекте Pages Functions следует учитывать несколько ключевых отличий:

• Поля конфигурации не совпадают точно между файлом Wrangler для Pages Functions и эквивалентом для Workers. Например, такие ключи конфигурации, как main, специфичные для Workers, не применяются к конфигурационному файлу Wrangler для Pages Function. Некоторые функции, поддерживаемые Workers, например алиасы модулей пока нельзя использовать в проектах Cloudflare Pages.
• Файл конфигурации Wrangler для Pages вводит новый ключ pages_build_output_dir, которая используется только для проектов Pages.
• Понятие окружения и наследование конфигурации в этом файле не является то же самое, что и Workers.
• Этот файл становится источник достоверных данных при использовании, а значит вы нельзя редактировать те же поля в панели управления как только начнете использовать этот файл.

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

Файл конфигурации Wrangler применяется локально при использовании wrangler pages dev. Это означает, что вы можете быстро проверять изменения конфигурации без входа в панель управления Cloudflare. Пример конфигурационного файла приведен ниже:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-app",
	"pages_build_output_dir": "./dist",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-app"
pages_build_output_dir = "./dist"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

Этот файл конфигурации Wrangler добавляет nodejs_compat флаг совместимости и привязку пространства имен KV к проекту Pages. Выполнение wrangler pages dev в каталоге проекта Pages с этим конфигурационным файлом Wrangler применит nodejs_compat флаг совместимости локально и предоставляет KV привязку в коде вашей Pages Function по адресу context.env.KV.

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

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

npx wrangler pages deploy

или точнее:

npx wrangler pages deploy --branch <PRODUCTION BRANCH>

Чтобы развернуть конфигурацию для preview-развёртываний, выполните ту же команду, находясь в ветке, настроенной для работы с развёртывания предпросмотра. Это задаст конфигурацию для всех Preview-деплоев, а не только для деплоев из конкретной ветки. На данный момент Pages не поддерживает конфигурацию на уровне веток.

Иногда требуется использовать разную конфигурацию для локальной среды, preview развёртываний и production. Переопределить конфигурацию для production и preview развёртываний можно с помощью [env.production] или [env.preview].

Ознакомьтесь со следующим файлом конфигурации Wrangler, чтобы узнать, как переопределить конфигурацию preview-развертываний:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"preview": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PREVIEW_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

Если вы развернули этот файл через wrangler pages deploy, name, pages_build_output_dir, kv_namespaces, а также vars применит конфигурацию как для локальной среды, так и для продакшена, тогда как env.preview переопределит kv_namespaces и vars для превью-развертываний.

Если вы хотите, чтобы конфигурационные значения применялись к local и preview, но переопределяли production, ваш файл будет выглядеть так:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"production": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PRODUCTION_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "8901234bfgd"

Всегда можно явно указать и переопределить значения как для preview, так и для production:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"preview": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PREVIEW_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		},
		"production": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PRODUCTION_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "6567875fvgt"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "6567875fvgt"

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

• name string обязательно

  • Имя вашего проекта Pages. Допускаются только буквы, цифры и дефисы.

• pages_build_output_dir string обязательно

  • Путь к каталогу вывода сборки вашего проекта. Например: ./dist.

• compatibility_date string обязательно

  • Дата в формате yyyy-mm-dd, который будет использоваться для определения того, какая версия Workers runtime применяется. См. Даты совместимости.

• compatibility_flags string[] необязательно

  • Список флагов, включающих функции из будущих версий среды выполнения Workers, обычно используемых вместе с compatibility_date. См. даты совместимости.

• send_metrics boolean необязательно

  • Должен ли Wrangler отправлять данные об использовании этого проекта в Cloudflare. По умолчанию используется true. Подробнее об этом можно узнать в нашем политика данных ↗.

• limits Limits необязательно

  • Настраивает ограничения на выполнение в среде выполнения. См. Лимиты.

• placement Placement необязательно

  • Укажите, как должны размещаться Pages Functions, чтобы свести к минимуму время прохождения запроса и ответа. См. Smart Placement.

• upload_source_maps boolean

  • Когда upload_source_maps имеет значение true, Wrangler загрузит серверные source map, являющиеся частью вашего проекта Pages, чтобы в логах отображались исправленные трассировки стека.

Ненаследуемые ключи можно задавать на верхнем уровне, но если хотя бы один ненаследуемый ключ переопределён для какой-либо среды (например,[[env.production.kv_namespaces]]), все ненаследуемые ключи также должны быть указаны в конфигурации окружения и переопределены.

Например, следующая конфигурация не будет работать:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"production": {
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[env.production.vars]
API_KEY = "8901234bfgd"

[[env.production.vars]] задаётся, чтобы переопределить [vars]. По этой причине [[kv_namespaces]] также нужно переопределить, задав [[env.production.kv_namespaces]].

Это будет работать для локальной разработки, но не пройдёт проверку при попытке развёртывания.

• vars object необязательно

  • Набор переменных окружения, которые нужно задать при развертывании вашей Function. См. Переменные окружения.

• d1_databases object необязательно

  • Список баз данных D1, к которым должна быть привязана ваша Function. См. Базы данных D1.

• durable_objects object необязательно

  • Список Durable Objects, к которым должна быть привязана ваша Function. См. Durable Objects.

• hyperdrive object необязательно

  • Указывает конфигурации Hyperdrive, к которым должна быть привязана ваша Function. См. Hyperdrive.

• kv_namespaces object необязательно

  • Список пространств имён KV, к которым должна быть привязана ваша Function. См. Пространства имён KV.

• queues.producers object необязательно

  • Указывает Queues Producers, привязанные к этой Function. См. Queues Producers.

• r2_buckets object необязательно

  • Список бакетов R2, к которым должна быть привязана ваша Function. См. Бакеты R2.

• vectorize object необязательно

  • Список индексов Vectorize, к которым должна быть привязана ваша Function. См. Индексы Vectorize.

• services object необязательно

  • Список service bindings, к которым должна быть привязана ваша Function. См. привязки к сервисам.

• analytics_engine_datasets object необязательно

  • Указывает наборы данных Analytics Engine, привязанные к этой Function. См. Workers Analytics Engine.

• ai object необязательно

  • Указывает привязку AI к этой Function. См. Workers AI.

Лимиты для проекта Pages настраиваются так же, как и для Workers. Подробнее см. это руководство для дополнительных сведений.

A привязка позволяет Pages Functions взаимодействовать с ресурсами Cloudflare Developer Platform. Используйте привязки, чтобы связать Pages Functions с ресурсами Cloudflare, такими как KV, Durable Objects, R2, а также D1. Вы можете настроить привязки как для Production, так и для Preview окружений.

D1 это бессерверная SQL-база данных Cloudflare. Function может обращаться к базе данных D1 (или нескольким базам), создав привязка к каждой базе данных для D1 Workers Binding API.

• Настройте привязки базы данных D1 через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим Привязка базы данных D1.

Durable Objects обеспечивают низкую задержку координации и согласованное хранение для платформы Workers.

• Настройте привязки пространства имён Durable Object через файл Wrangler так же, как они настраиваются в Cloudflare Workers.

• Взаимодействуйте с вашим Привязка пространства имён Durable Object.

Переменные окружения это тип привязки, позволяющий прикреплять текстовые строки или значения JSON к вашей Pages Function.

• Настройте переменные окружения через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим переменные окружения.

Hyperdrive привязки позволяют взаимодействовать с любой базой данных Postgres и делать к ней запросы прямо из Pages Function.

• Настройте привязки Hyperdrive через файл Wrangler так же, как они настраиваются в Cloudflare Workers.

Workers KV представляет собой глобальное хранилище данных типа «ключ-значение» с низкой задержкой. Данные хранятся в небольшом числе централизованных дата-центров, а после обращения кешируются в дата-центрах Cloudflare.

• Настройте привязки пространства имён KV через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим Привязка пространства имён KV.

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

• Настройте привязки производителя Queues через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим привязка Queues Producer.

Cloudflare R2 Storage позволяет разработчикам хранить большие объемы неструктурированных данных без высокой платы за исходящий трафик, характерной для обычных облачных хранилищ.

• Настройте привязки бакетов R2 через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим Привязки бакетов R2.

A Индекс Vectorize позволяет добавлять векторные эмбеддинги и выполнять по ним запросы для семантического поиска, классификации и других сценариев векторного поиска.

• Настройте привязки Vectorize через файл Wrangler так же, как они настраиваются в Cloudflare Workers.

Service binding позволяет вызывать Worker из вашей Pages Function. Привязка Pages Function к Worker позволяет отправлять HTTP-запросы к Worker без выхода этих запросов в интернет. Запрос немедленно вызывает нижестоящий Worker, что снижает задержку по сравнению с запросом к стороннему сервису. См. О service bindings.

• Настройте привязки служб через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим привязки к сервисам.

Workers Analytics Engine предоставляет аналитику, наблюдаемость и логирование данных из Pages Functions. Записывайте точки данных в привязке Pages Function, а затем запрашивайте эти данные с помощью SQL API.

• Настройте привязки Analytics Engine Dataset через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим Analytics Engine Dataset.

Workers AI позволяет запускать модели машинного обучения в сети Cloudflare прямо из вашего кода: будь то Workers, Pages или где угодно через REST API.

В отличие от других привязок, эта привязка ограничена одной привязкой AI на проект Pages Function.

• Настройте привязки Workers AI через файл Wrangler так же, как они настраиваются в Cloudflare Workers.
• Взаимодействуйте с вашим Привязка Workers AI.

Настройки локальной разработки, которые можно задать, одинаковы для Pages Functions и Cloudflare Workers. См. это руководство для дополнительных сведений.

В проектах Pages Functions файл Wrangler служит основным источником настроек. При входе в панель управления Cloudflare вы сможете увидеть те же поля, но не сможете их редактировать.

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