Cloudflare Pages — сервис для сборки и размещения статических сайтов. Он подключается к GitHub или GitLab, автоматически собирает и разворачивает изменения и создаёт отдельные preview-деплои для остальных веток. Готовые файлы также можно загружать напрямую через Wrangler.

Материал пригодится владельцу существующего Pages-проекта или разработчику, которому подходит этот процесс сборки. Понадобятся права на репозиторий, понятная команда сборки и папка результата. Для нового проекта Cloudflare рекомендует начать с Workers Static Assets; Pages продолжает обслуживать существующие проекты. Это рекомендация платформы, а не объявление о закрытии Pages. Текущая позиция Cloudflare.

Оглавление

Что такое Cloudflare Pages

Cloudflare Pages принимает исходный код из Git-репозитория или готовую папку со статическими файлами, а затем размещает результат в глобальной сети Cloudflare. Для Git-проекта сервис запускает новую сборку при каждом разрешённом изменении репозитория.

Фреймворк использовать необязательно. Можно развернуть обычные HTML-, CSS- и JavaScript-файлы либо проект, для которого команда сборки создаёт отдельную выходную папку.

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

📌
Материал основан на официальной документации и не подтверждён самостоятельным тестовым развёртыванием. Интерфейс, лимиты и команды сверены с первоисточниками 3 октября 2026 года. Облачная сборка и публикация в рамках подготовки не выполнялись.

Основные возможности

ВозможностьЧто даёт
Git-интеграцияАвтоматические сборки и деплои из публичных и приватных репозиториев GitHub или GitLab
Production branchВыбранная ветка используется для рабочей версии сайта; обычно это main или master
Preview-деплоиОстальные ветки получают отдельные версии сайта для проверки изменений
Настройки сборкиМожно указать команду сборки, выходную и корневую папки проекта
Переменные окруженияЗначения для сборки задаются при настройке проекта и изменяются после первой сборки
Direct UploadГотовые файлы загружаются через Wrangler или перетаскиванием в панели Cloudflare
Pages FunctionsСерверная логика выполняется на Cloudflare Workers и использует квоту соответствующего Workers-плана
Пользовательский доменНа Free-плане к одному Pages-проекту можно подключить до 100 доменов

Деплой из GitHub или GitLab

1. Подготовьте репозиторий

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

2. Подключите Git-провайдера

  1. Откройте Workers & Pages в панели Cloudflare.
  2. Выберите Create application → Pages → Connect to Git.
  3. Войдите через GitHub или GitLab.
  4. Предоставьте Cloudflare доступ к нужному репозиторию.
  5. Выберите репозиторий и перейдите к настройке проекта.

Для GitLab требуется роль Maintainer или выше. Авторизация GitLab предоставляет Pages доступ ко всем репозиториям аккаунта; в многопользовательском аккаунте Cloudflare другие его участники также смогут разворачивать доступные репозитории.

3. Настройте сборку

ПараметрЧто указать
Production branchВетку рабочей версии сайта, обычно main или master
Build commandКоманду, которую предоставляет выбранный фреймворк
Build output directoryПапку с файлами, которые нужно опубликовать
Root directoryПапку проекта внутри репозитория, если код находится не в корне
Environment variablesПеременные, необходимые во время сборки

В панели есть готовые настройки для ряда фреймворков. Например, для Gatsby официальная документация приводит команду gatsby build. Точные значения для остальных инструментов лучше брать из актуального руководства конкретного фреймворка.

Если сборка не нужна, оставьте поле Build command пустым. Cloudflare считает корень репозитория рабочей папкой, пока вы не зададите другой путь в Root directory.

4. Запустите первый деплой

Нажмите Save and Deploy. В журнале будет видно, как Cloudflare устанавливает зависимости, собирает проект и размещает выходную папку. После успешного завершения сервис покажет уникальный адрес сайта на поддомене pages.dev.

5. Проверьте результат

Откройте полученный URL и убедитесь, что:

  • главная страница загружается;
  • стили, скрипты и изображения доступны;
  • в проекте отображаются успешный статус деплоя и связанный коммит;
  • новое изменение production-ветки запускает следующую сборку, если автоматические деплои включены.

Если сразу после первого деплоя возникает ошибка DNS, документация Cloudflare рекомендует дождаться распространения записи или проверить адрес через другую сеть.

Direct Upload без Git-интеграции

Direct Upload подходит, когда проект собирается локально или в собственной системе CI/CD. До загрузки нужно самостоятельно выполнить команду сборки и подготовить папку с готовыми файлами.

Загрузка через Wrangler

Используйте поддерживаемую LTS-версию Node.js ≥22: этого требует проверенный Wrangler 4.147.0. Сначала выполните сборку локально и убедитесь, что dist/index.html и ресурсы существуют. Если проект выдаёт другую папку, замените ./dist на её путь. Команды login, создания проекта и deploy ниже обращаются к аккаунту Cloudflare; они нужны только при готовности публиковать выбранный проект.

# Авторизация
npx wrangler login

# Создание Pages-проекта
npx wrangler pages project create

# Загрузка готовых файлов
npx wrangler pages deploy ./dist

Wrangler запросит название проекта и production branch. Для preview-окружения укажите ветку:

npx wrangler pages deploy ./dist --branch=staging

Получить список проектов и уникальных preview-URL можно командами:

npx wrangler pages project list --json
npx wrangler pages deployment list

Wrangler принимает одну папку с файлами, но не ZIP-архив. Загрузка перетаскиванием в панели принимает папку или ZIP.

⚠️
Тип существующего проекта нельзя переключить между Git integration и Direct Upload. В проекте с Git-интеграцией можно вручную создавать деплои через Wrangler. Если не хотите запускать сборку при каждом пуше, отключите автоматические деплои всех веток. Загрузка перетаскиванием для такого проекта недоступна.

Папка functions при Direct Upload компилируется только при загрузке через Wrangler. Перетаскивание в панели её не поддерживает; файл _worker.js поддерживается обоими способами.

Preview-деплои

В Git-интегрированном проекте production branch создаёт рабочую версию сайта, а остальные ветки используются для preview-деплоев. Cloudflare также может добавлять сведения о preview-деплое в запрос на слияние (pull request).

Preview-адреса по умолчанию публичны. Заголовок X-Robots-Tag: noindex исключает их из поискового индекса, но не ограничивает доступ. Для закрытого просмотра включите Cloudflare Access и проверьте его в чистом сеансе браузера. Этот переключатель защищает preview, а не автоматически основной pages.dev и пользовательский домен.

Хеш-адрес относится к отдельному деплою; адрес вида staging.project.pages.dev — изменяемый псевдоним ветки, который указывает на её последний деплой.

Количество одновременно активных preview-деплоев для проекта не ограничено. Для Direct Upload preview можно создать через флаг --branch или выбрать preview-окружение при загрузке из панели.

Preview полезен, чтобы проверить сборку и показать изменения до объединения ветки. Успешная проверка означает, что отдельный preview-URL открывается и соответствует нужной ветке или коммиту.

Pages Functions

Pages Functions добавляет серверную обработку к сайту и работает на платформе Cloudflare Workers. Вызовы функций расходуют общую квоту Workers-плана аккаунта, включая обращения функции к KV и Durable Objects.

На Workers Free доступно 100 000 запросов в сутки. Это общая квота: например, 50 000 запросов Pages Functions и 50 000 других Workers-запросов исчерпают дневной лимит. Квота сбрасывается в полночь по UTC.

Запрос считается статическим и остаётся бесплатным и неограниченным только тогда, когда он не вызывает Function. Поэтому маршруты функций следует настраивать так, чтобы обычные файлы не попадали в серверную обработку без необходимости.

Лимиты

Значения из официальной документации, сверенные 3 октября 2026 года:

ПараметрFreeProBusiness
Одновременные сборки1520
Сборки в месяц5005 00020 000
Домены на проект100250500
Файлы на сайт20 000100 000100 000
Размер одного файла25 MiB25 MiB25 MiB

Для лимита 100 000 файлов на платном плане требуется переменная PAGES_WRANGLER_MAJOR_VERSION=4. Одна сборка завершается по тайм-ауту через 20 минут, а параллельные сборки считаются на уровне аккаунта.

Дополнительные ограничения:

  • до 100 Pages-проектов на аккаунт;
  • до 1 000 файлов при Direct Upload перетаскиванием;
  • до 20 000 файлов при загрузке через Wrangler на Free;
  • неограниченное количество активных preview-деплоев;
  • до 100 правил в файле _headers;
  • до 2 000 статических и 100 динамических правил в _redirects.

Для файлов крупнее 25 MiB Cloudflare рекомендует использовать R2. Лимиты могут меняться, поэтому перед миграцией большого проекта проверьте официальную страницу.

Полезные сценарии

Статический сайт из GitHub

Задача: разместить статический сайт с автоматическим обновлением из репозитория. Исходные данные — репозиторий с готовой статикой или проектом, создающим выходную папку. Подключите репозиторий, задайте production branch и параметры сборки. Результат проверяется по успешному статусу деплоя, связанному коммиту и рабочему адресу pages.dev. До изменения сохраните адрес предыдущего production-деплоя; для возврата используйте штатный rollback к проверенной версии. Preview не меняет основной сайт.

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

Предпросмотр изменений до объединения ветки

Задача: проверить изменения до их объединения с production-веткой. Создайте отдельную ветку и запрос на слияние (pull request). Pages соберёт preview-версию, которую можно проверить и передать коллегам. Наблюдаемый результат — отдельный URL с содержимым выбранной ветки.

Учитывайте месячный лимит сборок: частые изменения во множестве веток увеличивают число сборок.

Деплой из собственной системы CI/CD

Задача: самостоятельно выбирать момент развёртывания и среду сборки. Соберите проект в своей системе непрерывной интеграции и доставки (CI/CD) и передайте выходную папку через npx wrangler pages deploy ./dist. Этот вариант позволяет самостоятельно выбирать инструменты и момент развёртывания. Успех подтверждается записью в списке деплоев и доступностью опубликованной версии.

Тип проекта следует выбрать заранее: Direct Upload впоследствии нельзя преобразовать в Git-интегрированный проект.

Статический сайт с небольшим API

Задача: разместить интерфейс и несколько серверных маршрутов. Разместите интерфейс как статические файлы, а серверные маршруты реализуйте через Pages Functions. Проверьте статические страницы и каждый маршрут функции отдельно. Следите за общей дневной квотой Workers Free и не направляйте все запросы через функцию без необходимости.

Проверка результата и частые ошибки

Сборка завершается с ошибкой

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

Сайт открывается, но файлов нет

Чаще всего указана неверная выходная папка. Убедитесь, что после сборки она существует и содержит главную страницу и остальные ресурсы.

Репозиторий или production branch нельзя выбрать

Проверьте разрешения Git-провайдера и наличие хотя бы одной отправленной ветки. Для GitLab у подключающего пользователя должна быть роль Maintainer или выше.

Functions отсутствуют после Direct Upload

Используйте Wrangler и запускайте команду из папки, рядом с которой находится каталог functions. Загрузка перетаскиванием этот каталог не компилирует.

Деплои не запускаются автоматически

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

Официальные источники

Следующий шаг

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

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov