Деплой на Cloudflare Pages

Библиотека Vite формирует стандартный production-бандл через команду сборки, результатом которой становится директория dist. Именно этот каталог и является основной единицей публикации на статических хостингах, включая платформу Cloudflare Pages.

Ключевой принцип деплоя Vite-приложения заключается в том, что Cloudflare Pages не выполняет серверный Node.js-код в классическом виде. Вместо этого он раздаёт статические файлы через edge-инфраструктуру, поэтому вся логика сборки должна быть завершена до этапа публикации.

Сборка выполняется стандартной командой:

npm run build

или напрямую:

vite build

Результат помещается в папку:

dist/

Именно она указывается как output directory в настройках Cloudflare Pages.

Базовая конфигурация Vite под Cloudflare Pages

При деплое важно учитывать базовый путь (base path). В Cloudflare Pages приложение часто размещается в корне домена, но в случае проектов в поддиректориях требуется корректная настройка.

В vite.config.js:

import { defineConfig } from 'vite'

export default defineConfig({
  base: '/',
  build: {
    outDir: 'dist'
  }
})

Если проект размещается не в корне домена, например /app/, необходимо изменить:

base: '/app/'

Неправильное значение base приводит к ошибкам загрузки ассетов: JS и CSS файлы начинают запрашиваться по неверным путям.

Структура проекта перед деплоем

Типичный Vite-проект перед публикацией содержит:

project/
 ├─ dist/
 ├─ src/
 ├─ public/
 ├─ index.html
 ├─ vite.config.js
 ├─ package.json

Cloudflare Pages использует только результат сборки, поэтому src/ и конфигурационные файлы не попадают в продакшн.

Настройка Cloudflare Pages

Cloudflare Pages работает в двух основных режимах:

Git-based deployment
Direct upload (через CLI или drag-and-drop)

Git-based deployment

При подключении репозитория система автоматически:

устанавливает зависимости
запускает build command
публикует содержимое dist

Основные поля конфигурации:

Build command:
```
npm run build
```
Build output directory:
```
dist
```
Root directory (если монорепозиторий):
```
/ (или путь к пакету)
```

Деплой через Cloudflare Pages CLI

Для более контролируемых сценариев используется CLI:

npm install -g wrangler

Авторизация:

wrangler login

Деплой:

wrangler pages deploy dist

Этот способ полностью обходит Git-интеграцию и напрямую загружает статические файлы.

SPA routing и проблема 404

Одностраничные приложения (SPA), построенные на Vite, используют клиентский роутинг (например, React Router или Vue Router). Cloudflare Pages по умолчанию не знает о внутренних маршрутах и возвращает 404 при прямом переходе на URL вроде:

/dashboard
/profile/settings

Для решения используется файл _redirects.

Файл _redirects

Создаётся в папке public/:

public/_redirects

Содержимое:

/* /index.html 200

После сборки он попадает в dist/_redirects и сообщает Cloudflare Pages:

все маршруты перенаправлять на index.html
статус ответа 200

Это критически важно для SPA.

Обработка статических ресурсов

Vite автоматически хэширует ассеты:

assets/index-8f3a1c.js
assets/style-3a91cd.css

Cloudflare Pages эффективно кеширует такие файлы благодаря их неизменяемости.

Рекомендуемая стратегия кеширования:

HTML: no-cache
assets/*: immutable, long cache

Настройка заголовков (Headers)

Дополнительные HTTP-заголовки задаются через файл _headers:

public/_headers

Пример:

/*
  Cache-Control: no-cache

/assets/*
  Cache-Control: public, max-age=31536000, immutable

Это улучшает производительность и снижает нагрузку на edge-сеть.

Переменные окружения

Cloudflare Pages поддерживает environment variables, которые могут быть использованы на этапе сборки Vite.

В Vite переменные должны начинаться с:

VITE_

Пример .env:

VITE_API_URL=https://api.example.com

Использование в коде:

const apiUrl = import.meta.env.VITE_API_URL

В настройках Cloudflare Pages переменные задаются в разделе:

Settings → Environment variables

Важно: переменные доступны только во время build, а не в runtime.

Разделение окружений (Production / Preview)

Cloudflare Pages автоматически создаёт два типа окружений:

Production
Preview (для pull requests)

Vite-конфигурация может учитывать это:

export default defineConfig(({ mode }) => {
  return {
    define: {
      __APP_ENV__: JSON.stringify(mode)
    }
  }
})

Оптимизация сборки под edge-инфраструктуру

Cloudflare Pages работает на edge-сети, поэтому критично уменьшать размер бандла.

Рекомендации:

Code splitting

Vite поддерживает автоматический splitting:

build: {
  rollupOptions: {
    output: {
      manualChunks: {
        vendor: ['react', 'react-dom']
      }
    }
  }
}

Динамические импорты

const AdminPanel = await import('./admin/AdminPanel.vue')

Это уменьшает initial load.

Обработка больших SPA на Cloudflare Pages

При росте приложения важно учитывать:

количество JS чанков
размер initial bundle
latency edge-загрузки

Cloudflare Pages оптимизирует доставку через CDN, но не оптимизирует JS-архитектуру приложения.

Подключение API и ограничения

Cloudflare Pages не является backend-средой для Node.js, но поддерживает:

Pages Functions (serverless edge functions)
Workers API

Для Vite-приложений это означает:

frontend обращается к API напрямую
либо через edge functions

Пример вызова:

fetch('/api/user')

Использование Pages Functions

Структура:

functions/api/user.js

Пример:

export async function onRequest() {
  return new Response(JSON.stringify({ ok: true }), {
    headers: { 'Content-Type': 'application/json' }
  })
}

Это позволяет расширять Vite-приложение серверной логикой без отдельного backend.

Ошибки деплоя и диагностика

Типичные проблемы:

1. Белый экран

Причина:

неверный base
неправильные пути ассетов

2. 404 на внутренних маршрутах

Причина:

отсутствует _redirects

3. Переменные undefined

Причина:

отсутствие VITE_ префикса
не заданы env в Cloudflare

4. Сборка проходит локально, но падает в Pages

Причина:

различие Node версий
отсутствие зависимостей в production install

Итоговая архитектура деплоя

Типичный pipeline Vite + Cloudflare Pages:

Разработка в Vite dev server
Сборка vite build
Генерация dist
Загрузка в Cloudflare Pages
Распространение через edge CDN

Производственный сценарий деплоя

При использовании Git-интеграции процесс становится полностью автоматическим:

push в main
запуск build
публикация в production
создание preview для PR

Vite в этом процессе выступает исключительно как build tool, а Cloudflare Pages как delivery layer.

Производительность на edge

Edge-инфраструктура обеспечивает:

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

Vite-оптимизация усиливает эти свойства за счёт:

tree-shaking
esbuild трансформаций
минимизации CSS/JS

Совместимость с современными фреймворками

Vite используется с:

React
Vue
Svelte
SolidJS

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

Контроль качества перед публикацией

Перед деплоем проверяется:

корректность сборки
отсутствие runtime ошибок
валидность маршрутов SPA
размер бандла
наличие _redirects и _headers

Роль Vite в Cloudflare-экосистеме

Vite выполняет роль генератора production-артефактов, тогда как Cloudflare обеспечивает глобальную доставку этих артефактов пользователю через edge-сеть, минимизируя задержки и упрощая инфраструктуру до уровня статического хостинга с расширениями serverless-функций.