Деплой на Netlify - netlify-deployment

Введение

Netlify — это платформа, которая берет на себя деплой, хостинг и часть backend‑логики для фронтенд‑приложений и статических сайтов. Смотрите, здесь мы разберем, как настроить деплой на Netlify с нуля, какие режимы деплоя доступны, как организовать работу через Git, как управлять переменными окружения, доменами и откатами версий.

Я буду показывать вам типичные сценарии:

• деплой через GitHub / GitLab / Bitbucket;
• деплой локальной сборки через drag‑and‑drop и Netlify CLI;
• настройка команд сборки и директорий;
• работа с Netlify Functions;
• типичные ошибки деплоя и способы их отладки.

Цель статьи — чтобы вы могли уверенно настроить и поддерживать деплой на Netlify для типичного фронтенд‑проекта (React, Vue, Svelte, Next.js в статическом режиме, Astro и т.д.), а также понимать, как Netlify разворачивает ваш код «под капотом».

Что такое деплой на Netlify и как он устроен

Основная модель деплоя

Давайте начнем с общей схемы. Когда вы настраиваете проект в Netlify и связываете его с репозиторием Git:

1. Вы пушите изменения в репозиторий (например, в ветку main).
2. Netlify реагирует на изменение — забирает код из репозитория.
3. На выделенной машине запускается:
   • команда установки зависимостей (обычно автоматически);
   • команда сборки, которую вы указываете (например npm run build).
4. Netlify берет указанный каталог сборки (например dist или build) и превращает его в «деплой».
5. Готовый деплой становится доступен по URL вашего сайта.

Каждый деплой в Netlify — это неизменяемый снапшот. Это значит, что если вы загрузили одну версию сайта, она не перезаписывается следующей, а просто перестает быть «текущей». При необходимости вы можете сделать откат к любой предыдущей версии в пару кликов.

Основные типы деплоя

Netlify поддерживает несколько способов, как доставить ваш сайт на хостинг:

• автоматический деплой из Git;
• ручной деплой через drag‑and‑drop (архив или папка);
• деплой через Netlify CLI (из командной строки);
• деплой предварительных версий (Deploy Previews) из pull‑request.

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

Подготовка проекта к деплою на Netlify

Требования к структуре проекта

Важно, чтобы проект умел собираться в статическую папку (если это SPA или статический сайт). Обычно нужно:

• команда сборки (например в package.json):

{
  "scripts": {
    "build": "vite build"
  }
}

• итоговая папка (Vite по умолчанию создает папку dist).

Netlify на этапе создания сайта попросит указать:

• Build command — как собрать ваш проект;
• Publish directory — какую папку опубликовать.

Если вы уже знаете эти параметры, деплой пройдет гораздо быстрее и без лишних экспериментов.

Поддерживаемые типы проектов

На Netlify удобно деплоить:

• статические сайты без сборки (чистый HTML/CSS/JS);
• SPA (React, Vue, Svelte и т.п.);
• SSG‑проекты (Gatsby, Next.js в static export, Astro);
• генераторы документации (Docusaurus, VuePress и т.д.).

Для Node.js SSR, Django, Rails и других полноценных серверных фреймворков Netlify в «чистом виде» не подходит — здесь нужны адаптации (рендеринг на билде, функции без сервера и т.п.).

Деплой через Git: основной и рекомендуемый способ

Создание сайта из репозитория

Давайте разберем стандартный сценарий деплоя: репозиторий находится на GitHub.

1. Заходите в панель Netlify.
2. Нажимаете кнопку Add new site → Import an existing project.
3. Выбираете Git provider:
   • GitHub;
   • GitLab;
   • Bitbucket.
4. Авторизуетесь и даете Netlify доступ к нужным репозиториям.
5. Выбираете репозиторий с проектом.

Теперь Netlify спросит настройки сборки.

Настройка команды сборки и каталога публикации

На шаге настройки Build settings вам нужно заполнить:

• Branch to deploy — ветка, из которой будет собираться production‑сайт (обычно main или master);
• Build command — команда, выполняющая сборку проекта;
• Publish directory — путь к папке, в которой появляются итоговые файлы сайта.

Примеры настройки под разные сборщики:

Пример для Vite + React

• Build command: npm run build
• Publish directory: dist

Фрагмент package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build" // Команда сборки для Netlify
  }
}

Пример для Create React App

• Build command: npm run build
• Publish directory: build

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build" // Netlify выполнит эту команду
  }
}

Пример для Next.js со статическим экспортом

Вам нужно включить экспорт в статический HTML:

{
  "scripts": {
    "build": "next build",
    "export": "next export",  // Экспорт в статическую папку
    "netlify-build": "next build && next export" // Команда для Netlify
  }
}

И в Netlify:

• Build command: npm run netlify-build
• Publish directory: out

Комментарии:

• Здесь мы создаем отдельный скрипт netlify-build, чтобы Netlify выполнял и сборку, и экспорт.
• Папка out будет содержать финальный статический сайт.

Автоматические деплои при пуше

После первой успешной настройки Netlify подключает вебхуки к вашему Git‑провайдеру. Теперь любой пуш в выбранную ветку:

1. Запускает новый билд.
2. Создает новый деплой.
3. Автоматически переключает «текущую» версию сайта на свежесобранную (если сборка прошла успешно).

Вы увидите, что для каждого коммита появляется отдельный деплой, а в логах видно:

• шаг установки зависимостей;
• выполнение build‑команды;
• генерацию деплоя и его публикацию.

Если вы хотите временно выключить авто‑деплои (например, перед крупным релизом):

1. Откройте сайт в Netlify.
2. Зайдите в вкладку Deploys.
3. Найдите раздел Build settings → Build & deploy.
4. В Deploy contexts настройте режимы, либо отключите Auto publish через настройки ветки.

Ручной деплой: drag‑and‑drop и загрузка архивов

Иногда вам нужен максимально простой сценарий: собрать проект локально и просто загрузить уже готовые файлы на Netlify. Это удобно:

• для прототипов;
• для статичных лендингов, собранных вручную;
• когда у вас нет доступа к Git‑репозиторию.

Деплой через drag‑and‑drop

Смотрите, я покажу вам, как это работает:

1. Локально собираете сайт:
   • npm install
   • npm run build
2. Открываете в Netlify ваш сайт (или создаете пустой).
3. Переходите во вкладку Deploys.
4. В секции Deploys увидите область с подписью Drag and drop your site output here.
5. Перетаскиваете туда:
   • папку со статическими файлами, или
   • zip‑архив с содержимым выходной папки.

Netlify создаст деплой из содержимого этой папки/архива и опубликует его. Важно, чтобы в корне были статические файлы (как минимум index.html).

Особенность такого способа: он не привязан к Git, новые версии нужно загружать вручную.

Деплой через загрузку ZIP файла

Интерфейс похож на drag‑and‑drop, но вы:

1. Нажимаете кнопку Upload deploy (или аналогичную).
2. Выбираете zip‑архив с вашим сайтом.

Netlify распакует архив и опубликует содержимое. Структура должна быть такой же, как при drag‑and‑drop.

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

Если вы предпочитаете работать из терминала и контролировать процесс деплоя напрямую с вашей машины, пригодится Netlify CLI.

Установка CLI

Установите CLI через npm:

npm install -g netlify-cli      # Глобальная установка CLI

Проверьте, что команда доступна:

netlify --version               # Вывод версии CLI

Авторизация в аккаунте Netlify

Давайте разберемся, как связать ваш локальный терминал с аккаунтом:

netlify login                   # Откроет браузер для авторизации

После успешного логина CLI сможет создавать сайты и выполнять деплой от вашего имени.

Инициализация проекта

Перейдите в корень проекта и выполните:

netlify init

Что здесь происходит:

• CLI спросит, хотите ли вы связать проект с существующим сайтом на Netlify или создать новый;
• если создаете новый, попросит указать:
  • имя сайта (можно оставить случайно сгенерированное),
  • build‑команду,
  • publish‑директорию.

В результате появится файл netlify.toml (если вы согласитесь его создать), а локальная папка будет связана с вашим сайтом в Netlify.

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

Теперь вы можете деплоить прямо из командной строки.

Деплой черновика (draft deploy)

netlify deploy --build --alias test-deploy

Комментарии:

• --build — Netlify CLI сам выполнит команду сборки, указанную при init или в netlify.toml.
• --alias — задает имя для предпросмотра (получится URL вида https://test-deploy--mysite.netlify.app).

Такой деплой не становится production‑версией сайта, он используется для предпросмотра.

Production‑деплой через CLI

netlify deploy --build --prod

Комментарии:

• Этот деплой станет текущей производственной версией.
• Команда пригодится, когда вы хотите контролировать сборку локально, но деплоить на Netlify.

Пример netlify.toml с настройками

Теперь вы увидите, как это выглядит в конфигурационном файле:

# Файл netlify.toml лежит в корне проекта

[build]
  command = "npm run build"       # Команда сборки
  publish = "dist"                # Папка с итоговыми файлами

[dev]
  command = "npm run dev"         # Локальный dev-сервер
  port = 5173                     # Порт, на котором работает Vite
  targetPort = 4173               # Порт, к которому Netlify будет проксировать запросы

[[redirects]]
  from = "/*"                     # Все маршруты
  to = "/index.html"              # Отдают index.html (SPA-роутинг)
  status = 200                    # Код ответа

Смотрите, здесь я добавил пример редиректа для SPA. Так вы избежите типичной ошибки с 404 при перезагрузке страницы на вложенном маршруте.

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

Часто деплой на Netlify упирается в работу с API‑ключами, токенами и другими секретами. Их нельзя хранить в коде, поэтому используются переменные окружения.

Где задаются переменные окружения

Для каждого сайта:

1. Откройте сайт в Netlify.
2. Перейдите в Site settings.
3. Найдите раздел Environment variables.
4. Нажмите Edit variables и добавьте пары ключ‑значение.

Пример:

• VITE_API_URL = https://api.example.com
• VITE_API_KEY = some-secret-key

Netlify передаст эти переменные в процесс сборки. Если ваш бандлер использует префиксы (например, VITE_ для Vite, REACT_APP_ для CRA), обязательно придерживайтесь их.

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

Давайте посмотрим пример для Vite:

// src/api.ts

// Здесь мы читаем значения переменных окружения
const API_URL = import.meta.env.VITE_API_URL
const API_KEY = import.meta.env.VITE_API_KEY

export async function fetchData() {
  // Обратите внимание, что ключ часто нужно передавать в заголовках
  const response = await fetch(`${API_URL}/data`, {
    headers: {
      "Authorization": `Bearer ${API_KEY}` // Используем секретный ключ
    }
  })

  if (!response.ok) {
    throw new Error("Ошибка при запросе данных")
  }

  return response.json()
}

Комментарии:

• Здесь показано, как в типичном SPA‑проекте взять параметры из окружения.
• На клиенте эти значения окажутся в итоговом JavaScript, поэтому критические секреты лучше выносить в Netlify Functions (о них ниже).

Контексты окружений (production, deploy previews и т.д.)

Netlify позволяет задавать разные значения переменных для разных окружений:

• Production;
• Deploy Preview;
• Branch deploys.

Например, можно сделать так:

• production:
  • VITE_API_URL = https://api.prod.example.com
• deploy previews:
  • VITE_API_URL = https://api.staging.example.com

Это удобно для тестирования в превью‑деплоях.

Deploy Previews и branch deploys

Deploy Previews (предпросмотр для pull‑request)

Каждый pull‑request в GitHub (или аналогичный merge request) может автоматически разворачивать свою версию сайта на Netlify. Это сильно облегчает ревью.

Как это работает:

1. Вы открываете PR в ветку main.
2. Netlify видит новый PR и:
   • забирает код из ветки;
   • выполняет билд;
   • создает отдельный деплой вида https://deploy-preview-15--mysite.netlify.app.
3. Ссылка на превью добавляется в UI Netlify и (при интеграции) в обсуждение PR на GitHub.

Вы можете открыть это превью, проверить изменения и только потом мержить PR.

Настройка:

• В большинстве случаев Deploy Previews включены по умолчанию для подключенного репозитория.
• Управлять ими можно в Site settings → Build & deploy → Deploy contexts.

Branch deploys (деплой конкретных веток)

Помимо PR, можно автоматически деплоить конкретные ветки, например:

• develop — стенд для интеграционного тестирования;
• feature-x — временный стенд для команды.

Схема:

1. В Build & deploy → Branches указываете ветки для деплоя.
2. Netlify будет создавать отдельные деплои с URL вида:
   • https://develop--mysite.netlify.app

Таким образом, у вас появляются независимые окружения на разных ветках.

Управление доменами и HTTPS

Временный домен Netlify

Сразу после создания сайта Netlify выдает поддомен вида:

• mysite-12345.netlify.app

Вы можете использовать его как есть или настроить свой домен.

Подключение собственного домена

1. Перейдите в Site settings → Domain management.
2. Нажмите Add custom domain.
3. Введите домен, например example.com или поддомен app.example.com.
4. Следуйте подсказкам по настройке DNS.

Как правило, вам нужно добавить в DNS:

• запись CNAME для поддомена (например app) на mysite-12345.netlify.app;
• либо A‑записи на IP Netlify (если настраиваете root‑домен).

Netlify подскажет нужные значения.

Автоматический HTTPS (Let’s Encrypt)

После успешной настройки домена Netlify автоматически:

• создает сертификат Let’s Encrypt;
• включает HTTPS;
• может настроить принудительный редирект с HTTP на HTTPS.

Опция редиректа включается в Domain management → HTTPS.

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

Netlify Functions: серверная логика без отдельного сервера

Когда одного статического фронтенда мало, на помощь приходят Netlify Functions — это функции, которые выполняются на стороне сервера в ответ на HTTP‑запросы.

Где размещать функции

По умолчанию:

• создайте папку netlify/functions в корне проекта;
• каждая функция — отдельный файл.

Теперь давайте посмотрим пример.

Простейшая функция «hello»

// netlify/functions/hello.js

// Netlify будет вызывать экспортируемую функцию handler
exports.handler = async (event, context) => {
  // Здесь можно прочитать параметры запроса
  const name = event.queryStringParameters.name || "гость"

  // Возвращаем ответ в формате JSON
  return {
    statusCode: 200, // Код успешного ответа
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message: `Привет, ${name}` })
  }
}

Комментарии:

• Функция принимает event (информация о запросе) и context (данные о среде выполнения).
• Возвращаем объект с statusCode, headers и body.

Обратите внимание: путь до этой функции в вашем сайте будет:

• /api/hello — если в настройках Functions base path стоит /api (часто по умолчанию).

Вызов функции с фронтенда

Теперь вы увидите, как эту функцию вызвать из вашего фронтенда:

// src/helloClient.ts

export async function sayHello(name: string) {
  // Отправляем GET-запрос на нашу функцию
  const response = await fetch(`/.netlify/functions/hello?name=${encodeURIComponent(name)}`)

  if (!response.ok) {
    throw new Error("Ошибка при вызове функции")
  }

  // Читаем JSON-ответ
  const data = await response.json()
  return data.message
}

Комментарии:

• В продакшне путь по умолчанию: /.netlify/functions/<имя_файла>.
• Лучше вынести базовый URL в переменные окружения, если вы вызываете функцию из другого домена.

Настройка пути к функциям

Если вы хотите задать другое расположение папки с функциями, добавьте в netlify.toml:

[build]
  command = "npm run build"
  publish = "dist"
  functions = "netlify/functions"   # Путь к директории с функциями

Теперь при деплое Netlify найдет и задеплоит ваши функции вместе с фронтендом.

Редиректы и маршрутизация (особенно важны для SPA)

Одна из частых проблем при деплое SPA на Netlify — ошибка 404 при перезагрузке страницы на вложенных маршрутах. Например, вы заходите на /profile, обновляете страницу и получаете 404.

Чтобы этого избежать, нужно настроить редиректы.

Файл _redirects

Самый простой способ — создать файл _redirects в папке публикации (или в корне проекта, если сборщик копирует его в выходной каталог). В нем вы описываете правила.

Пример для SPA:

/*    /index.html   200

Комментарии:

• Любой путь (/*) будет отдавать index.html.
• Код 200 означает успешный ответ (не редирект, а внутреннее перенаправление).

Использование redirects в netlify.toml

Альтернативный способ — описать редиректы в netlify.toml. Мы уже смотрели пример, повторю его отдельно:

[[redirects]]
  from = "/*"             # Любой путь
  to = "/index.html"      # Всегда отдаем index.html
  status = 200            # Не меняем URL в адресной строке

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

Примеры более сложных редиректов

Перенос старого пути на новый

[[redirects]]
  from = "/old-path"      # Старый путь
  to = "/new-path"        # Новый путь
  status = 301            # Постоянный редирект

API‑прокси на внешний сервис

[[redirects]]
  from = "/api/*"                     # Локальный путь
  to = "https://api.example.com/:splat" # Проксируем на внешний API
  status = 200
  force = true                        # Принудительно, даже если есть реальный файл

Комментарии:

• Это полезно, если вы хотите скрыть реальный адрес бэкенда или обойти CORS.

Откат деплоя (rollbacks) и управление версиями

Каждый деплой на Netlify хранится в истории. Это не только удобно, но и безопасно: если свежий релиз «сломал» сайт, вы можете быстро вернуться к рабочей версии.

Как откатиться к предыдущему деплою

1. Откройте вкладку Deploys в панели сайта.
2. Выберите нужный деплой в списке (по дате, хэшу коммита и т.д.).
3. Нажмите Promote to production (или аналогичную кнопку).

Netlify моментально переключит production‑сайт на выбранную версию. Сама сборка уже выполнена раньше, поэтому ничего пересобирать не нужно.

Заморозка авто‑деплоев

Иногда удобно:

• откатиться к стабильной версии;
• временно остановить автоматическую публикацию новых деплоев.

Для этого в Build & deploy настройках можно:

• отключить Auto publish для production;
• при этом новые деплои будут собираться, но не становиться активной версией до тех пор, пока вы явно не нажмете Publish.

Типичные ошибки деплоя и их отладка

Ошибка сборки (build failed)

Причины:

• отсутствует команда build в package.json;
• неправильный путь к publish директории;
• нехватка зависимостей.

Как выявить:

1. Откройте вкладку Deploys → конкретный деплой → Logs.
2. Просмотрите лог от начала до конца:
   • шаг установки зависимостей;
   • вывод команды сборки;
   • возможные stack trace.

Пример частой проблемы: вы указали publish = "build", а проект (например Vite) создает папку dist. Netlify завершит сборку успешно, но сайт окажется пустым или с ошибками. Поэтому всегда сверяйтесь с тем, какую папку реально создает ваш сборщик.

Ошибка с переменными окружения

Симптомы:

• в продакшне API‑запросы летят на неправильный URL;
• в консоли браузера видно undefined вместо ожидаемого значения.

Проверьте:

• заданы ли переменные в Environment variables в Netlify;
• соответствуют ли имена префиксам (например VITE_);
• не забыли ли вы пересобрать проект (Netlify делает это при каждом деплое, но если вы меняли только переменные окружения, иногда полезно инициировать новый билд).

404 при обновлении страницы

Мы уже разбирали это выше: причина — отсутствие правил SPA‑маршрутизации. Решение:

• добавить _redirects с правилом /* /index.html 200, либо
• прописать [[redirects]] в netlify.toml.

CORS при вызовах внешнего API

Если ваш фронтенд стучится прямо в другой домен, браузер может блокировать запросы из‑за CORS. Варианты решения:

• настроить CORS на стороне бэкенда;
• сделать Netlify Function‑прокси;
• использовать redirects‑прокси (см. пример выше).

Заключение

Netlify заметно упрощает деплой фронтенд‑проектов: вы связываете репозиторий, настраиваете пару параметров — и дальше любая новая версия кода автоматически собирается и публикуется. При этом платформа сохраняет каждую сборку, позволяет быстро откатываться, разворачивать временные окружения для PR, настраивать домены и HTTPS.

Мы разобрали:

• деплой через Git, drag‑and‑drop и Netlify CLI;
• как указать команду сборки и publish‑директорию;
• работу с переменными окружения и разными контекстами;
• Deploy Previews и branch deploys;
• базовую конфигурацию netlify.toml, включая redirects;
• Netlify Functions и пример простой серверной логики;
• типичные проблемы при деплое и пути их решения.

Опираясь на эти подходы, вы можете выстроить понятный и предсказуемый процесс деплоя для большинства SPA и статических сайтов на Netlify, а затем постепенно добавлять более сложные вещи — edge‑функции, продвинутые редиректы, интеграции с CI/CD и т.п.

Частозадаваемые технические вопросы и ответы

1. Как задать разные команды сборки для разных веток

Используйте контексты в netlify.toml:

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

[context.production]
  command = "npm run build:prod"     # Для основной ветки

[context.branch-deploy]
  command = "npm run build:staging"  # Для веток

[context.deploy-preview]
  command = "npm run build:preview"  # Для PR

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

2. Как задеплоить монорепозиторий с несколькими приложениями

В netlify.toml укажите base для каждого сайта или настройте отдельные сайты, указывая поддиректорию:

[build]
  base = "apps/app1"      # Корень конкретного приложения
  command = "npm run build"
  publish = "dist"

При создании сайта через UI в разделе Basic build settings укажите Base directory как apps/app1. Для другого приложения создайте отдельный сайт с apps/app2.

3. Как задеплоить проект без package.json и сборки

Если у вас чистый статический сайт:

1. Просто положите HTML/CSS/JS в папку, где в корне есть index.html.
2. При создании сайта в Netlify:
   • оставьте Build command пустой;
   • в Publish directory укажите эту папку (или корень репозитория).
3. Netlify сразу опубликует файлы без этапа сборки.

4. Как использовать частный (private) Git‑репозиторий

Netlify работает с приватными репозиториями через OAuth‑доступ:

1. При подключении GitHub/GitLab/Bitbucket разрешите доступ к приватным репозиториям.
2. В списке репозиториев выберите нужный private‑репозиторий.
3. Netlify будет использовать свои деплой‑ключи или токены, вам не нужно вручную добавлять SSH‑ключи.

Если доступ ограничен организацией, убедитесь, что приложению Netlify в GitHub выдан доступ к этой организации.

5. Как ограничить доступ к сайту паролем на Netlify

Для простого базового доступа:

1. Откройте Site settings → Domain management → Access control.
2. Включите Password protection.
3. Задайте пароль.

Netlify автоматически настроит защищенный доступ (Basic Auth). Для более сложной авторизации используйте Netlify Identity или внешние провайдеры аутентификации в связке с Netlify Functions.