Деплой на Vercel

Сборка Vite-приложения ориентирована на статическую генерацию артефактов, которые могут быть размещены на любом CDN или хостинг-платформе, включая Vercel. Основной этап подготовки заключается в формировании production-бандла с помощью команды:

npm run build

По умолчанию Vite формирует каталог dist, содержащий оптимизированные ресурсы: JavaScript-чункы, CSS-файлы, статические ассеты и HTML-entrypoint.

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

Базовая структура сборки Vite

После выполнения production build структура каталога dist обычно включает:

  • index.html — точка входа приложения
  • assets/ — сжатые JS и CSS файлы с хешированием
  • статические ресурсы (из public/)

Хеширование файлов обеспечивает корректное кэширование на уровне CDN Vercel, предотвращая проблемы с устаревшими версиями.

Настройка base-пути для Vercel

Vercel размещает приложения в корне домена, поэтому в большинстве случаев дополнительная настройка base не требуется.

Однако при нестандартных сценариях (монорепозитории, поддиректории) конфигурация Vite должна учитывать путь публикации:

// vite.config.js
import { defineConfig } from 'vite'

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

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

base: '/app/'

Неправильная настройка base приводит к ошибкам загрузки ассетов после деплоя.

Подключение проекта к Vercel

Vercel автоматически поддерживает Vite-проекты без дополнительной конфигурации в большинстве случаев. Основной принцип работы:

  1. Детектируется framework Vite
  2. Выполняется npm install
  3. Выполняется npm run build
  4. Публикуется каталог dist

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

Конфигурация vercel.json

Для более контролируемого деплоя используется файл vercel.json, позволяющий явно определить output directory и rewrite-правила.

{
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build",
      "config": {
        "distDir": "dist"
      }
    }
  ]
}

В более современных конфигурациях часто достаточно:

{
  "outputDirectory": "dist"
}

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

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

Решение заключается в настройке rewrite-правила:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

Это обеспечивает передачу всех запросов на входной HTML, после чего маршрутизация обрабатывается на стороне клиента.

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

Vite использует префикс VITE_ для всех переменных окружения, доступных в клиентском коде.

Пример использования:

VITE_API_URL=https://api.example.com

В коде:

const apiUrl = import.meta.env.VITE_API_URL

На Vercel переменные задаются в разделе Environment Variables. Они разделяются по окружениям:

  • Production
  • Preview
  • Development

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

Preview deployments

Одной из ключевых особенностей Vercel является автоматическое создание preview-сборок для каждой ветки или pull request.

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

  • отдельный build для каждой ветки
  • изолированные URL
  • независимые environment variables

Такая модель особенно полезна при параллельной разработке интерфейсов и экспериментальных фич.

Оптимизация сборки под Vercel

Vercel использует глобальную CDN-инфраструктуру, поэтому важно учитывать следующие аспекты оптимизации:

Code splitting

Vite автоматически разбивает код на чанки:

import('./module.js')

Это снижает начальный размер бандла и ускоряет загрузку.

Asset handling

Статические файлы, размещённые в public/, копируются без обработки. Рекомендуется использовать:

  • src/assets для импортируемых ресурсов
  • public/ только для неизменяемых файлов

Кэширование

Vercel применяет агрессивное кеширование для файлов с хешами. Это требует:

  • стабильной стратегии именования
  • избегания ручных изменений файлов в dist

Monorepo сценарии

При использовании Vite в монорепозитории (например, pnpm workspaces или turborepo) требуется указание корневой директории проекта.

В vercel.json:

{
  "installCommand": "pnpm install",
  "buildCommand": "pnpm build",
  "outputDirectory": "apps/web/dist"
}

Важно, чтобы Vercel выполнял сборку именно из нужного workspace-пакета.

Ошибки деплоя и их причины

Пустой экран после деплоя

Чаще всего связано с:

  • неправильным base
  • некорректными путями к ассетам
  • отсутствием index.html в output

404 на внутренних страницах

Причина:

  • отсутствие rewrite на index.html

Ошибки env-переменных

Причина:

  • отсутствие префикса VITE_
  • неправильное окружение (Preview vs Production)

Поведение build-процесса на Vercel

Vercel использует изолированное окружение:

  • чистая файловая система
  • установка зависимостей с нуля
  • отсутствие локальных кэшей (если не настроено иначе)

Это делает поведение сборки воспроизводимым, но требует корректно описанных зависимостей в package.json.

Статические функции и serverless-расширения

Хотя Vite предназначен для фронтенда, Vercel позволяет расширять проект serverless-функциями:

/api
  hello.js

Пример функции:

export default function handler(req, res) {
  res.status(200).json({ message: 'ok' })
}

Такая архитектура позволяет объединять фронтенд на Vite и backend-логику в одном деплое.

Контроль версий сборки

Vercel фиксирует каждую сборку как отдельный deployment. Это обеспечивает:

  • возможность отката
  • сравнение версий
  • изолированное тестирование

Каждый deployment привязан к конкретному commit SHA.

Поведение при обновлении приложения

После пуша в основную ветку:

  • запускается новый build
  • формируется новый immutable deployment
  • старые версии сохраняются для отката

Кеширование CDN обновляется автоматически после завершения деплоя.

Оглавление