Развёртывание на Cloudflare Pages

Когда документация написана, её нужно опубликовать в интернете, чтобы команда и пользователи могли её читать. Для EpoCanvas Docs рекомендуется хостинг на Cloudflare Pages: не нужно покупать сервер и настраивать Nginx — достаточно загрузить статические файлы, а HTTPS-сертификаты выдаются автоматически. Сам этот сайт (docs.epocanvas.com) опубликован именно способом, описанным в статье; все скриншоты консоли ниже взяты из реального процесса развёртывания.

---

Подготовка

Что вам понадобится

Пункт	Пояснение
Аккаунт Cloudflare	Бесплатная регистрация на dash.cloudflare.com; для сервиса Pages платный тариф не требуется
Успешная локальная сборка	Сначала проверьте, что pnpm run build отрабатывает и каталог dist/ корректно создаётся; см. Быстрый старт
Node.js + pnpm	Команды развёртывания зависят от локальной среды разработки; требования к версиям — как в главе «Быстрый старт»

Как выбрать один из двух способов развёртывания

Рисунок: сравнение двух путей развёртывания на Cloudflare Pages. Слева — сборка на своём компьютере и прямая загрузка на edge через Wrangler (реально используется этим сайтом), справа — автоматическая облачная сборка, запускаемая GitHub Webhook.

Параметр сравнения	Способ 1: прямая загрузка из командной строки	Способ 2: автоматическая сборка из Git
Как выполняется	Локальный запуск pnpm run deploy	Запускается автоматически при отправке кода на GitHub
Порог входа	Низкий, две команды	Средний, требуется однократная настройка в консоли
Подходящие сценарии	Первый запуск, обслуживание одним человеком, быстрые обновления	Совместная работа нескольких людей, желание «закоммитил — значит опубликовано»
Используется этим сайтом	✅ Да (можно проверить в консоли)	Не включён, можно добавить в любой момент

Совет

Оба способа могут работать параллельно: в повседневной работе используется автоматическая сборка из Git, а при срочном исправлении ошибки локальный pnpm run deploy сразу перезаписывает опубликованную версию.

Совсем не хотите вводить команды?

На странице Быстрый старт есть кнопки развёртывания в один клик для Cloudflare, Vercel и Netlify: нажмите, авторизуйте аккаунт, подтвердите настройки — и сайт документации опубликуется в вашем облачном аккаунте; подробнее в разделе Развёртывание в один клик. Кнопка Cloudflare использует статический хостинг Workers, это отдельный путь, не совпадающий со способом Pages, описанным на этой странице; для статического сайта документации качество доступа у них одинаковое — выберите любой один путь.

---

Способ 1: прямая загрузка из локальной командной строки (рекомендуется для первого раза)

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

Шаг 1: вход в аккаунт Cloudflare

В проекте уже предустановлен Wrangler (официальный инструмент командной строки Cloudflare); при первом использовании нужно авторизоваться через браузер:

npx wrangler login

После запуска в терминале появится сообщение Opening a link in your default browser..., браузер откроет страницу авторизации Cloudflare; после нажатия Allow терминал сообщит об успешном входе. Проверить состояние входа можно командой:

npx wrangler whoami

Осторожно

Если запустить развёртывание без входа, терминал выдаст You are not authenticated. Please run 'wrangler login'., и никакого развёртывания не произойдёт.

Шаг 2: сборка и загрузка одной командой

В package.json проекта предустановлена команда публикации одной кнопкой:

pnpm run deploy

Она равнозначна двум последовательным шагам: сначала astro build компилирует весь сайт в каталог dist/ и создаёт поисковый индекс, затем вызывается wrangler pages deploy dist, который загружает результат прямо в Cloudflare. Реальный вывод на этапе сборки выглядит так:

23:54:01 [build] 181 page(s) built in 20.78s
23:54:01 [build] Complete!

После завершения загрузки Wrangler выведет адрес предпросмотра этого развёртывания. Имя проекта задано заранее в скрипте deploy (--project-name epocanvas-docs), поэтому интерактивный запрос при развёртывании не появляется.

Шаг 3: найдите свой проект в консоли

Откройте dash.cloudflare.com, в меню слева нажмите Compute (Workers & Pages) — откроется список проектов. На рисунке ниже отмечены три ключевых места:

Рисунок: список проектов Workers & Pages. ① переход в Workers & Pages через меню слева; ② кнопка Create application для создания нового проекта; ③ наш проект epocanvas-docs с доменом доступа epocanvas-docs.pages.dev и временем последнего развёртывания.

Нажмите на имя проекта, чтобы открыть его страницу; вкладка Deployments показывает полную историю развёртываний:

Рисунок: страница истории развёртываний. ① имя проекта; ② вкладка Deployments; ③ к производственному домену привязаны одновременно docs.epocanvas.com (собственный домен) и epocanvas-docs.pages.dev (домен по умолчанию); ④ у каждой записи развёртывания отмечены ветка и информация о коммите; ⑤ статус и время развёртывания.

Заметка

Каждый запуск pnpm run deploy добавляет новую запись в начало списка, и она автоматически становится текущей производственной версией. История сохраняется в списке, поэтому при возникновении проблем можно в любой момент выполнить откат.

---

Конфигурация сборки проекта с прямой загрузкой

Откройте вкладку Settings, чтобы увидеть отличие проекта с прямой загрузкой от проекта на Git:

Рисунок: вкладка Settings. ① вход в Settings; ② в поле Git repository показано Connect (не подключён) — проекту с прямой загрузкой не нужна конфигурация сборки из Git, вся сборка выполняется локально.

Совет

Здесь же видно преимущество прямой загрузки: средой сборки является ваш собственный компьютер, на который не влияет очередь сборок Cloudflare; платой за это является необходимость выполнять команду обновления именно на том компьютере, с которого выполняется развёртывание.

---

Способ 2: автоматическая сборка с подключением репозитория Git (необязательно)

Если хочется, чтобы «отправка кода автоматически публиковала сайт», можно подключить проект к репозиторию GitHub — тогда Cloudflare будет собирать его в облаке автоматически.

Шаг 1: переход к созданию проекта

На странице списка проектов Workers & Pages нажмите кнопку Create application в правом верхнем углу (отметка ② на рисунке из шага 3 способа 1) и выберите вкладку Pages.

Шаг 2: подключение репозитория Git

1. На экране создания выберите Connect to Git;
2. Авторизуйте доступ Cloudflare к вашему аккаунту GitHub;
3. В списке репозиториев выберите репозиторий документации epocanvas-docs;
4. Нажмите Начать настройку.

Шаг 3: заполнение конфигурации сборки

В разделе «Настройка сборки и развёртывания» укажите следующую конфигурацию:

Параметр	Значение
Пресет фреймворка	Astro
Команда сборки	pnpm run build
Каталог вывода сборки	dist

Шаг 4: проверка автоматической сборки

Нажмите Сохранить и развернуть, и Cloudflare автоматически выполнит первую сборку. После этого при каждой отправке кода в ветку main Cloudflare будет автоматически подтягивать изменения, собирать сайт и публиковать его. Журнал сборки каждого развёртывания можно посмотреть во вкладке Deployments проекта, нажав на соответствующую запись.

Осторожно

На странице Settings проекта с интеграцией Git появляется дополнительный блок конфигурации сборки (пресет фреймворка, команда сборки и т.д.) — интерфейс отличается от проекта с прямой загрузкой. Если вы не находите конфигурацию сборки в Settings, значит текущий проект использует прямую загрузку, и это нормальная ситуация.

---

Привязка собственного домена

Выданным Cloudflare по умолчанию доменом epocanvas-docs.pages.dev можно пользоваться сразу; привязка собственного домена (например, docs.epocanvas.com) занимает всего несколько минут.

Шаг 1: открытие настроек собственного домена

На странице проекта откройте вкладку Custom domains и нажмите Set up a custom domain:

Рисунок: вкладка Custom domains. ① вход во вкладку; ② кнопка Set up a custom domain; ③ привязанный docs.epocanvas.com со статусом Active и включённым SSL.

Шаг 2: добавление домена и ожидание активации

1. Нажмите Set up a custom domain и введите свой поддомен (например, docs.epocanvas.com);
2. Если DNS домена уже обслуживается в Cloudflare, CNAME-запись добавится автоматически; для домена, обслуживаемого в другом месте, нужно вручную добавить CNAME-запись, указывающую на <имя проекта>.pages.dev;
3. Дождитесь выдачи сертификата (обычно 2–5 минут); когда статус изменится на Active (как на рисунке выше, ③), сайт станет доступен по новому домену.

HTTPS-сертификаты Cloudflare выдаёт и продлевает автоматически; ручное оформление или настройка не требуются.

---

Проверка результата развёртывания

Проверка HTTP-статуса из командной строки

curl -sI https://epocanvas-docs.pages.dev

Реальный ответ:

HTTP/2 200
date: Fri, 11 Sep 2026 15:32:39 GMT
content-type: text/html; charset=utf-8

Значение 200 означает, что сайт исправен. После привязки собственного домена повторите проверку, заменив URL на свой домен.

Поэтапная проверка в браузере

Проверка	Ожидаемый результат
Главная и любая страница документации открываются	Страница отрисовывается полностью, без белого экрана
Свежие изменения вступили в силу	Только что отредактированный раздел виден на опубликованном сайте
Поиск по всему сайту через Ctrl+K	Находятся новейшие статьи (индекс создаётся при сборке)
Переключение светлой/тёмной темы	Переключается нормально и сохраняется после обновления страницы

---

Частые проблемы при развёртывании

После развёртывания содержимое сайта не обновилось?

Сначала исключите кэш жёстким обновлением браузера (Ctrl+F5 / Cmd+Shift+R); если всё ещё не обновляется, на странице Deployments консоли проверьте время последней записи, а затем сравните с доменом предпросмотра развёртывания через curl -sI.

На собственном домене ошибка SSL handshake (Error 525)?

Выдаче сертификата нужно 2–5 минут, чтобы распространиться по всему миру, — подождите и обновите страницу жёстким обновлением; в это время можно пользоваться доменом по умолчанию epocanvas-docs.pages.dev.

Команда pnpm run deploy выдаёт ошибку Project not found?

Сначала выполните npx wrangler whoami, чтобы убедиться, что вы вошли; затем сверьте --project-name в скрипте deploy из package.json с именем проекта в консоли.

Остальные пункты диагностики — в разделе Частые вопросы и устранение неполадок.