Деплой на Vercel - vercel-deployment на практике

Введение

Vercel — это платформа, которая берет на себя сборку и деплой фронтенд‑приложений и серверлес‑функций. Вам не нужно думать о серверах, контейнерах и сложной DevOps‑части. Достаточно подключить репозиторий, настроить несколько параметров — и проект начинает автоматически обновляться при каждом push.

Смотрите, я покажу вам, как устроен деплой на Vercel с нуля: от первого развертывания до настройки окружений, доменов и переменных среды. Мы затронем как “кнопочный” деплой через веб‑интерфейс, так и деплой через CLI, а также разберем файл конфигурации vercel.json, который дает вам точный контроль над процессом.

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

Как Vercel видит ваш проект

Vercel ориентирован в первую очередь на:

• Next.js
• React SPA (Create React App, Vite и т.п.)
• Static Site Generators (Nuxt Static, Gatsby, Astro)
• Чистый статический фронтенд (HTML, CSS, JS)
• Серверлес‑функции (API routes, standalone функции)

Общий принцип такой:

1. Vercel забирает код (из Git‑репозитория или из загруженного архива).
2. Определяет “framework preset” — по package.json, структуре файлов и наличию конфигов.
3. Запускает сборку с помощью выбранной команды (например, npm run build).
4. Результат сборки (build‑артефакты) размещается на edge‑инфраструктуре.
5. Для каждой сборки создается Preview Deployment — отдельный URL.
6. При необходимости один из деплоев помечается как Production и привязывается к вашему домену.

Важно понимать: каждая сборка — это отдельный, неизменяемый деплой. Vercel не “перезаписывает” файлы на сервере, а выкатывает новый билд и перенастраивает маршрутизацию.

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

Чтобы было проще ориентироваться, давайте перечислим базовые понятия:

• Проект (Project) — логическая единица в Vercel, связана с репозиторием и доменами.
• Деплой (Deployment) — конкретная версия кода, собранная и выложенная на Vercel.
• Preview Deployment — деплой из ветки, отличной от production‑ветки, или из Pull Request.
• Production Deployment — “боевая” версия, доступная по основному домену.
• Окружения (Environments) — Development, Preview и Production.
• Переменные окружения (Environment Variables) — значения, которые подставляются в процессе сборки или во время выполнения функций.

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

Первый деплой на Vercel через веб‑интерфейс

Регистрация и подключение Git‑репозитория

1. Заходите на сайт Vercel и проходите регистрацию (обычно через GitHub/GitLab/Bitbucket).
2. После входа нажимаете кнопку "New Project".
3. Выбираете вкладку “Import Git Repository”.
4. Разрешаете Vercel доступ к вашему аккаунту Git‑провайдера (если делаете это в первый раз).
5. Выбираете нужный репозиторий.

Здесь Vercel попытается автоматически определить фреймворк. Например:

• Если в package.json есть next и скрипт next build — выберется пресет Next.js.
• Если есть react‑scripts — выберется Create React App.
• Если есть vite — будет пресет Vite.

Настройка параметров проекта перед первым деплоем

На этапе импорта проекта вам покажут форму с настройками:

• Framework Preset — обнаруженный фреймворк.
• Root Directory — корневая папка проекта, если проект находится в поддиректории репозитория.
• Build Command — команда сборки (например, npm run build).
• Output Directory — директория с готовыми статическими файлами (для SPA и статических сайтов).
• Install Command — команда для установки зависимостей (npm install, pnpm install и т.п.).

Если вы, к примеру, деплоите Vite‑проект, обычно достаточно:

• Build Command: npm run build
• Output Directory: dist

Vercel часто подставляет это автоматически, но смотрите внимательно и при необходимости исправляйте.

Запуск первого деплоя

Когда все параметры выставлены:

1. Нажимаете “Deploy”.
2. Vercel запускает процесс:
   • скачивает репозиторий;
   • устанавливает зависимости;
   • запускает сборку;
   • загружает билд.
3. В реальном времени отображается лог сборки.

После окончания вы увидите:

• URL Preview Deployment (по шаблону что‑то вроде project-name-xyz.vercel.app).
• Кнопку “Visit” для открытия деплоя.
• Если выбрана production‑ветка (по умолчанию main/master), можно сразу пометить деплой как Production.

С этого момента при каждом push в выбранные ветки Vercel будет автоматически создавать новые деплои.

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

Иногда удобнее управлять деплоем из терминала. Для этого используется Vercel CLI.

Установка и авторизация

Сначала установите CLI глобально:

npm install -g vercel
# Устанавливаем Vercel CLI глобально

Затем выполните авторизацию:

vercel login
# CLI спросит ваш email или предложит войти через Git-провайдера

После авторизации CLI будет привязан к вашему аккаунту.

Простой деплой локального проекта

Давайте разберемся на примере минимального статического сайта. Допустим, у вас есть папка my-site с index.html.

Перейдите в эту папку и запустите:

cd my-site
vercel
# Запустится пошаговый конфигуратор деплоя

CLI задаст вам несколько вопросов:

• Link to existing project? — если проект уже создан в Vercel.
• Project name — имя нового проекта.
• In which directory is your code located? — путь к исходникам.
• Which scope should it belong to? — ваш личный аккаунт или организация.

После вопросов начнется сборка (для статического сайта сборка по сути отсутствует — файлы просто загружаются).

Для Production‑деплоя используется команда:

vercel --prod
# Делает деплой напрямую в продакшен окружение

Это удобно, если у вас, например, не настроен Git‑репозиторий или вы хотите быстро проверить локальные изменения без коммита.

Привязка каталога к уже существующему проекту

Если вы сначала импортировали проект через веб‑интерфейс, а потом хотите управлять им через CLI, удобно связать локальную папку с проектом:

vercel link
# CLI покажет список ваших проектов на Vercel
# Вы выбираете нужный, и создается локальный .vercel/project.json

После этого обычная команда vercel будет понимать, к какому проекту относится этот каталог.

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

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

Базовая структура vercel.json

Простейший пример:

{
  "version": 2,
  "builds": [
    {
      "src": "index.html",
      "use": "@vercel/static"
    }
  ],
  "routes": [
    {
      "src": "/about",
      "dest": "/about.html"
    }
  ]
}

Комментарии здесь нельзя добавить из‑за формата JSON, но давайте объясню по шагам:

• version: 2 — текущая схема конфигурации Vercel.
• builds — список билдов: какие файлы обрабатывать и какими билдерами.
• routes — правила маршрутизации: какие URL куда перенаправлять.

На практике, если вы используете современный фреймворк (Next.js и т.п.), vercel.json нужен не всегда. Но он очень полезен, когда:

• вам нужно явно настроить custom routes;
• вы хотите задать headers, redirects, rewrites;
• вы добавляете серверлес‑функции не через встроенные возможности фреймворка.

Пример: настройка rewrite для SPA

Для одностраничных приложений (React SPA, Vue SPA) нужно, чтобы все маршруты возвращали index.html, иначе при обновлении страницы по адресу /dashboard сервер вернет 404.

Здесь я размещаю пример, чтобы вам было проще понять:

{
  "version": 2,
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/index.html"
    }
  ]
}

Что происходит:

• src: "/(.*)" — регулярное выражение, которое matчит любой путь.
• dest: "/index.html" — всегда возвращаем главный HTML.

Так React Router (или любой другой роутер на клиенте) сам разберет, какой компонент отрисовать.

Пример: редиректы и заголовки

Давайте посмотрим, что происходит в следующем примере:

{
  "version": 2,
  "routes": [
    {
      "src": "^/old-blog/(.*)",
      "status": 301,
      "headers": { "Location": "https://blog.example.com/$1" }
    },
    {
      "src": "/secure/(.*)",
      "dest": "/secure/$1",
      "headers": {
        "Cache-Control": "no-store"
      }
    }
  ]
}

Здесь:

• Первый маршрут делает постоянный редирект с /old-blog/... на внешний домен.
• Второй маршрут добавляет заголовок Cache-Control для защищенных страниц.

Окружения и автоматические деплои

Production, Preview и Development

Vercel разделяет окружения:

• Production — основное боевое окружение.
• Preview — все деплои из непроизводственных веток и Pull Requests.
• Development — локальный dev‑сервер через vercel dev.

Как это выглядит на практике:

• Коммит в main (или другой выбранной production‑ветке) создает Production Deployment.
• Коммит в feature/login создает Preview Deployment, например:
  • feature-login-abc.vercel.app
• Pull Request в GitHub тоже создает Preview Deployment, который привязан к PR.

Настройка production‑ветки

Вы можете указать, какая ветка считается “боевой”:

1. Откройте проект в Vercel.
2. Перейдите во вкладку Settings.
3. В разделе Git задайте Production Branch (обычно main или master).

Теперь все коммиты в эту ветку будут автоматически деплоиться как продакшен.

Локальное окружение через vercel dev

Иногда полезно запускать проект с учетом настроек Vercel, но локально. Для этого есть команда:

vercel dev
# Запускает локальный dev-сервер с эмуляцией Vercel окружения

Особенно удобно, если вы тестируете:

• серверлес‑функции;
• rewrites/redirects;
• поведение с переменными окружения.

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

Типы переменных и их области действия

В Vercel переменные окружения привязаны к окружениям:

• Development — используются при локальной разработке и vercel dev.
• Preview — применяются при сборке и выполнении Preview Deployment.
• Production — для боевого окружения.

Вы можете задать разные значения для каждого окружения, например:

• API_URL для тестового сервера в Preview.
• API_URL для боевого сервера в Production.

Настройка переменных через веб‑интерфейс

Чтобы добавить переменную:

1. Зайдите в проект.
2. Откройте Settings.
3. Перейдите в раздел Environment Variables.
4. Нажмите “Add”.
5. Заполните:
   • Name — имя переменной, например, NEXTPUBLICAPI_URL.
   • Value — значение.
   • Environment — выберите Development/Preview/Production.

В Next.js есть важное правило: переменные, которые должны быть доступными на клиенте, должны начинаться с NEXTPUBLIC. Это позволяет разделить приватные значения (для сервера) и публичные.

Использование переменных в коде

Посмотрим на примере Next.js:

// pages/index.js

export default function Home() {
  // Здесь мы читаем переменную окружения, доступную на клиенте
  const apiUrl = process.env.NEXT_PUBLIC_API_URL

  return (
    <div>
      <p>Текущий API URL: {apiUrl}</p>
    </div>
  )
}

Комментарии в этом коде подсказывают:

• process.env.NEXTPUBLICAPI_URL подставляется на этапе сборки.
• Значение берется из настроек Vercel в зависимости от окружения деплоя.

Если вы меняете переменные окружения, важно помнить: нужно запустить новый деплой, чтобы изменения вступили в силу (для build‑time переменных).

Серверлес‑функции и деплой API

Vercel позволяет вам деплоить не только фронтенд, но и backend‑логику в виде serverless functions. Давайте разберемся на примере.

API routes в Next.js

В Next.js функции API создаются в папке pages/api. При деплое на Vercel они автоматически превращаются в серверлес‑функции.

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

// pages/api/hello.js

export default function handler(req, res) {
  // Здесь мы обрабатываем HTTP-запрос
  // req содержит запрос, res - объект ответа

  res.status(200).json({ message: 'Hello from Vercel API' })
  // Возвращаем JSON-ответ с кодом 200
}

Когда вы деплоите Next.js проект на Vercel:

• URL /api/hello будет вызывать эту функцию.
• Vercel сам организует инфраструктуру serverless (AWS Lambda/Edge Functions).

Отдельные функции в чистом проекте

Если вы не используете Next.js, можно создавать функции вручную. Например, структура:

• api/
  • time.js
• public/
  • index.html

Файл api/time.js:

// api/time.js

module.exports = (req, res) => {
  // Здесь мы получаем текущую дату и время
  const now = new Date().toISOString()

  // Отправляем JSON-ответ с текущим временем
  res.status(200).json({ now })
}

При деплое на Vercel этот файл станет серверлес‑функцией по адресу /api/time.

Vercel сам поймет, что папка api содержит функции, если используется соответствующий билд конфигурации (например, через vercel.json или автоопределение).

Деплой статических сайтов и SPA

Чистый статический сайт

Если у вас обычный сайт без сборщика (index.html, styles.css, script.js), деплой через Vercel максимально простой:

1. Создаете репозиторий с этими файлами в корне.
2. Импортируете репозиторий в Vercel.
3. В настройках проекта:
   • Build Command: оставляете пустым (нет сборки).
   • Output Directory: указываете . (текущая директория).

Vercel будет просто раздавать эти файлы как статические ресурсы.

SPA на базе сборщика (React, Vue, Vite)

Для SPA важно правильно указать:

• Build Command — команды сборки.
• Output Directory — куда складывается билд.

Например, для Create React App:

• Build Command: npm run build
• Output Directory: build

Для Vite:

• Build Command: npm run build
• Output Directory: dist

И не забываем про SPA‑маршрутизацию. Для этого, как мы уже обсуждали, добавляем vercel.json с rewrite всех путей на index.html.

Настройка доменов и Production Deployment

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

Когда проект на Vercel уже деплоится, вы можете привязать к нему свой домен.

Шаги:

1. Откройте проект.
2. Перейдите во вкладку Domains.
3. Нажмите “Add”.
4. Введите домен, например, example.com.
5. Vercel покажет инструкции по настройке DNS.

Если домен зарегистрирован у стороннего регистратора, нужно:

• либо изменить NS‑записи на NS‑серверы Vercel;
• либо добавить A/AAAA/CNAME записи, которые укажет Vercel.

После настройки домена:

• Production Deployment становится доступен по вашему домену.
• Preview Deployment могут использовать поддомены типа preview.example.com, если вы их настроите.

Переключение Production Deployment

Каждый новый успешный деплой в production‑ветку автоматически становится текущим Production Deployment. Если нужно откатиться:

1. Откройте вкладку Deployments.
2. Найдите нужный старый деплой.
3. Нажмите кнопку Promote to Production (название может немного меняться).
4. Vercel переключит домен на выбранный деплой.

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

Оптимизация и типичные проблемы при деплое

Время сборки и кэширование зависимостей

Vercel кэширует:

• node_modules (в разумных пределах);
• .next, .output и другие build‑артефакты.

Это помогает ускорять повторные сборки. Однако иногда кэш может “сломаться” (например, после крупного обновления зависимостей). В таком случае:

• В веб‑интерфейсе во время запуска деплоя можно выбрать опцию “Clear cache”.
• Через CLI можно использовать флаг:

vercel --force
# Форсирует новый деплой, не используя кэш

Комментарии к этому примеру:

• --force заставляет Vercel заново установить зависимости и пересобрать проект.
• Полезно при отладке странных ошибок сборки.

Ошибки сборки из‑за фреймворка

Иногда Vercel неправильно определяет фреймворк или сборку. Например:

• У вас монорепозиторий, и нужный проект не в корне.
• Несколько разных package.json.

В таких случаях:

1. Укажите Root Directory в настройках проекта (Settings → General → Root Directory).
2. Явно задайте Build Command и Output Directory.
3. При необходимости используйте vercel.json для более точной настройки.

Проблемы с переменными окружения

Наиболее частые ситуации:

• Переменная не определена на Preview или Production (вы задали ее только для одного окружения).
• Переменная меняется, но приложение по‑прежнему использует старое значение.

Здесь важно помнить:

• build‑time переменные “зашиваются” в билд. Для их обновления нужен новый деплой.
• runtime переменные (в serverless‑функциях) читаются при каждом вызове, но изменения вступают в силу только после перезапуска функций (обычно это происходит естественно при новом деплое).

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

Заключение

Деплой на Vercel строится вокруг простой идеи: каждая версия кода превращается в отдельный, неизменяемый билд, который платформа автоматически раскатывает на edge‑инфраструктуру. Вам достаточно один раз настроить проект, подключить репозиторий, задать команды сборки и при необходимости описать дополнительные правила в vercel.json.

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

• как сделать первый деплой через веб‑интерфейс и через CLI;
• как устроены окружения Production, Preview и Development;
• как управлять переменными окружения и доменами;
• как деплоить статические сайты, SPA и serverless‑функции;
• как решать типичные проблемы со сборкой и кэшем.

Дальше вы можете расширять конфигурацию: добавлять rewrites, защищенные маршруты, разделять конфигурации по окружениям и строить полноценный CI/CD на базе Git‑веток и Pull Requests. При этом сам процесс деплоя остается прозрачным — любой коммит соответствует конкретному URL, к которому всегда можно вернуться или продвинуть в продакшен.

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

Как задать разные Build Command для разных веток

Это не настраивается напрямую в интерфейсе Vercel. Используйте scripts в package.json и проверяйте переменную окружения VERCEL_ENV или ветку. Например:

{
  "scripts": {
    "build": "node build.js"
  }
}

А в build.js:

// Определяем окружение Vercel
const env = process.env.VERCEL_ENV
// Для preview запускаем одну сборку, для production - другую
if (env === 'preview') {
  // Здесь запускаем команды для preview
} else {
  // Здесь запускаем команды для production
}

Как ограничить деплой только определенных веток

В Settings → Git можно указать, какие ветки должны триггерить деплой. Для остальных можно отключить автоматический деплой и запускать его вручную через CLI:

vercel --prod
# Деплой текущего состояния, даже если ветка не в списке разрешенных

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

Создайте отдельный проект Vercel для каждого приложения и для каждого укажите свою Root Directory. Внутри монорепо можете использовать общие библиотеки, а сборка каждого приложения будет происходить из своей папки.

Как использовать кастомный Docker‑образ на Vercel

Классический Docker деплой Vercel не поддерживает. Если нужен контроль на уровне контейнера, используйте backend на другой платформе (Render, Fly, Kubernetes), а фронтенд и edge‑функции держите на Vercel. Связывайте их через API_URL в переменных окружения.

Как включить HTTP Basic Auth для всего сайта

Прямой глобальной Basic Auth в Vercel нет. Можно:

• реализовать проверку в middleware (например, в Next.js middleware);
• либо проксировать трафик через внешний reverse‑proxy с Basic Auth.