Деплой на Netlify

Vite формирует продакшен-сборку как статический набор файлов, пригодный для размещения на CDN или любом static hosting. Основной результат работы команды сборки:

npm run build

По умолчанию формируется директория dist, содержащая:

  • HTML entry point (index.html)
  • оптимизированные JS-чанки (ES modules)
  • CSS файлы, извлечённые из модулей
  • ассеты (изображения, шрифты и т.д.) с хешированием имен
  • дополнительные чанки для code splitting

Ключевая особенность Vite — предварительная сборка через Rollup, что обеспечивает стабильную структуру выходных файлов, удобную для деплоя на Netlify без серверной логики.

Базовая модель деплоя на Netlify

Netlify работает с двумя основными сценариями:

  • деплой через Git-репозиторий (GitHub/GitLab/Bitbucket)
  • ручной или CLI-деплой через Netlify CLI

В обоих случаях Netlify ожидает:

  • build command: npm run build
  • publish directory: dist

Эта модель напрямую совпадает с дефолтной конфигурацией Vite, что делает интеграцию минимальной.

Конфигурация проекта для Netlify

Файл netlify.toml

Основной способ описания поведения деплоя — netlify.toml в корне проекта:

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

Здесь задаются:

  • команда сборки
  • директория публикации
  • версия Node.js для сборочного окружения

SPA и проблема маршрутизации

Vite-приложения часто строятся как SPA (React, Vue, Svelte). В таком случае маршрутизация происходит на клиенте через History API. Проблема Netlify заключается в том, что при прямом заходе на путь вроде:

/dashboard/settings

сервер пытается найти файл по этому пути и возвращает 404.

Решение через redirects

Создаётся файл _redirects в директории public:

/*    /index.html   200

Этот механизм заставляет Netlify отдавать index.html для всех маршрутов, позволяя SPA-роутеру обрабатывать URL.

Альтернативный вариант через netlify.toml:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Настройка base path в Vite

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

Vite использует параметр base:

// vite.config.js
export default {
  base: "/",
}

Если приложение размещается в поддиректории:

export default {
  base: "/app/",
}

Это влияет на:

  • пути к ассетам
  • ссылки на скрипты
  • корректность загрузки чанков

Ошибка в base часто приводит к 404 на JS-файлы после деплоя.

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

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

Пример .env:

VITE_API_URL=https://api.example.com

В коде:

console.log(import.meta.env.VITE_API_URL)

Netlify Environment Variables

В Netlify переменные задаются:

  • через UI (Site settings → Environment variables)
  • через CLI
  • через netlify.toml (ограниченно)

Важно учитывать, что:

  • переменные доступны только во время build
  • изменение требует пересборки
  • секреты не должны попадать в клиентский код

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

Vite уже включает базовую оптимизацию, но для Netlify важны дополнительные аспекты:

Code splitting

import("./heavy-module.js")

Каждый динамический импорт создаёт отдельный chunk, который Netlify отдаёт как статический файл.

Asset hashing

Файлы получают имена вида:

assets/index-8f3a1c2d.js

Это позволяет:

  • агрессивное кеширование
  • отсутствие конфликтов версий

Кеширование на Netlify

Netlify автоматически применяет CDN-кеширование, но можно уточнить правила через netlify.toml:

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

Это особенно важно для Vite-ассетов, так как они уже хешированы и безопасны для долгого кеширования.

Деплой через Git интеграцию

При подключении репозитория Netlify выполняет:

  1. clone проекта
  2. установка зависимостей (npm install)
  3. выполнение build command
  4. публикация dist

Настройки:

  • Build command: npm run build
  • Publish directory: dist
  • Node version: 18+ или 20+

Преимущество этого подхода — автоматический деплой при каждом push.

Деплой через Netlify CLI

CLI позволяет управлять деплоем вручную:

npm install -g netlify-cli
netlify login
netlify deploy

Для продакшена:

netlify deploy --prod

CLI полезен для:

  • локального тестирования сборки
  • быстрых preview deploy
  • проверки конфигурации без Git

Обработка ошибок 404 и fallback

Типичная проблема SPA после деплоя — белый экран или 404 при обновлении страницы.

Причины:

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

Корректная конфигурация redirect устраняет проблему полностью.

Netlify Functions в связке с Vite

Netlify поддерживает serverless функции, которые могут использоваться вместе с Vite-frontend.

Структура:

netlify/
  functions/
    api.js

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

export async function handler() {
  return {
    statusCode: 200,
    body: JSON.stringify({ ok: true })
  }
}

Вызов с фронтенда:

fetch("/.netlify/functions/api")

Это позволяет:

  • скрывать серверную логику
  • реализовывать прокси к API
  • обрабатывать секретные ключи

Монорепозитории и Vite + Netlify

В монорепозиториях (pnpm, turborepo) важно явно указать:

  • root directory
  • build command с переходом в пакет

Пример:

[build]
  command = "pnpm --filter web build"
  publish = "packages/web/dist"

Частые проблемы при деплое

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

Причины:

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

2. 404 на ассеты

Причины:

  • неправильный build.outDir
  • конфликт publicPath/base

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

Причины:

  • отсутствие префикса VITE_
  • переменные не заданы в Netlify
  • попытка использовать env на клиенте без пересборки

4. Неправильная версия Node

Vite требует современный Node.js. Старые версии вызывают:

  • ошибки esbuild
  • сбои Rollup
  • некорректную установку зависимостей

Предпросмотр деплоев (Deploy Previews)

Netlify автоматически создаёт preview-версии для pull request.

Особенности:

  • отдельный URL
  • отдельное окружение переменных (опционально)
  • изолированная сборка

Это удобно для проверки Vite-изменений до merge.

Работа с большими ассетами

При использовании больших изображений или видео:

  • лучше хранить в CDN или external storage
  • избегать включения в src/assets
  • использовать lazy loading

Vite обрабатывает ассеты через import:

import img from "./image.png"

Netlify раздаёт их как статические файлы с кешированием.

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

  • Vite формирует статический dist
  • Netlify публикует его как CDN-сайт
  • SPA routing обеспечивается redirects
  • ассеты кешируются по хешам
  • окружение управляется через env variables
  • функции добавляют serverless слой при необходимости
Оглавление