Как опубликовать сайт на Vercel: от репозитория до собственного домена

Vercel может собирать сайт из Git-репозитория и создавать новую версию после каждого push. Сам deploy обычно занимает несколько минут. Ошибки чаще возникают вокруг него: неверная корневая папка, отсутствующие переменные окружения, случайная публикация тестовой ветки или незавершенная настройка домена.

Ниже приведен маршрут через GitHub и панель Vercel. Он подходит для статических сайтов и поддерживаемых JavaScript-фреймворков. Конкретную команду сборки всегда сверяйте с README проекта.

До подключения Vercel проект должен воспроизводимо собираться локально. Выполните штатные команды, например:

Не копируйте их механически, если проект использует другой пакетный менеджер. Смотрите lock-файл и инструкции репозитория.

Проверьте:

· код отправлен в GitHub;

· рабочая ветка отделена от main;

· git status чистый;

· в репозитории нет .env и секретов;

· команда сборки завершается без ошибки;

· результат не зависит от незакоммиченного локального файла;

· версия среды зафиксирована там, где это нужно проекту.

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

В панели Vercel выберите добавление проекта и импорт Git-репозитория. Подключите GitHub и дайте доступ только к нужным репозиториям, если политика команды это позволяет.

Во время импорта Vercel предлагает:

· имя проекта;

· framework preset;

· root directory;

· build command;

· output directory;

· переменные окружения.

Для обычного проекта автоопределение фреймворка часто достаточно. В монорепозитории особенно внимательно укажите root directory: это папка конкретного сайта, где находятся его package.json и конфигурация.

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

Локальный .env.local не отправляется в Git. Значения нужно добавить в настройках Vercel. У платформы есть отдельные среды Local, Preview и Production, поэтому один и тот же ключ может иметь разные значения.

Разделяйте как минимум:

· тестовую и рабочую базу;

· preview- и production-ключи внешних API;

· публичные настройки и серверные секреты.

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

После добавления или изменения переменной создайте новый deploy. Уже собранная версия обычно не получает новое значение задним числом.

В интеграции с Git каждый push в ветку, отличную от production branch, создает preview deployment. У него отдельный URL. Merge в production branch, обычно main, создает production deployment.

Рабочий цикл:

1. создайте ветку;

2. внесите ограниченное изменение;

3. отправьте ветку на GitHub;

4. откройте pull request;

5. дождитесь preview URL;

6. проверьте сайт и логи;

7. только затем объедините изменения в main.

Preview важен не только для дизайна. Он проверяет сборку в удаленной среде, маршруты, серверные функции, переменные и интеграции. При этом не используйте production-базу в preview по умолчанию: тестовая форма может создать настоящую заявку или изменить рабочие данные.

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

Типовые причины:

Зависимость не записана в package.json, отличается регистр имени файла или локально используется незакоммиченный файл. Linux-среда может различать Header.tsx и header.tsx, даже если локальная система была менее строгой.

Добавьте ее в нужную среду Vercel и перезапустите deploy. Не вставляйте значение в исходник.

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

Верните рекомендуемые настройки фреймворка или укажите фактическую папку результата. Не все проекты создают dist; Next.js, например, обычно настраивается интеграцией автоматически.

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

Успешный статус deploy означает, что сборка и размещение завершились. Он не подтверждает бизнес-поведение.

Откройте preview в приватном окне и проверьте:

· главную страницу и прямые ссылки на вложенные маршруты;

· форму с правильными и ошибочными данными;

· вход и выход, если есть авторизация;

· запросы к API;

· загрузку изображений и шрифтов;

· мобильный экран;

· пустые состояния и сообщения об ошибке;

· отсутствие ключей и внутренних трассировок в браузере;

· логи серверных функций после действия.

Если сайт индексируется поиском, проверьте title, description, canonical, robots.txt, sitemap и код ответа. Страница с красивой ошибкой может визуально выглядеть нормально, но возвращать неверный статус.

В настройках проекта добавьте домен, например example.com или www.example.com. Vercel покажет DNS-записи, которые нужно создать у регистратора или DNS-провайдера.

Не копируйте универсальные значения из сторонней статьи: нужная запись зависит от домена и текущей конфигурации. Используйте значения из панели конкретного проекта.

После изменения DNS:

1. дождитесь подтверждения домена в Vercel;

2. проверьте HTTPS;

3. выберите основной вариант с www или без;

4. настройте перенаправление второго варианта;

5. откройте несколько маршрутов по новому адресу;

6. проверьте ссылки в письмах, callback URL и настройках API;

7. обновите canonical и sitemap.

Распространение DNS может занять время. Не меняйте записи несколько раз подряд, пока не проверили их через панель и DNS-инструмент.

Git-интеграция позволяет вернуть код через новый commit или revert. Vercel также хранит историю deployments. Для командной работы предпочтительнее исправление в Git: тогда репозиторий снова соответствует production.

После запуска наблюдайте:

· ошибки сборки и функций;

· коды ответов;

· время выполнения критичных маршрутов;

· расходы и лимиты;

· успешность главной формы или покупки;

· срок домена и состояние DNS.

Если откатили deployment только в панели, зафиксируйте причину и приведите production branch в то же состояние. Иначе следующий push снова вернет проблему.

· сборка проходит из чистого репозитория;

· секреты находятся в Vercel Environment Variables;

· preview использует тестовые внешние ресурсы;

· основной путь проверен в приватном окне;

· прямые URL не дают 404;

· логи не раскрывают чувствительные данные;

· production branch определена явно;

· домен и HTTPS подтверждены;

· есть понятный способ отката;

· владелец получает уведомления о сбоях.

У статического сайта файлы создаются во время build и раздаются посетителю. У проекта с serverless-функциями часть кода выполняется при запросе. Это влияет на диагностику, переменные и стоимость.

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

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

Одностраничное приложение может работать при переходах внутри интерфейса, но давать 404 при открытии /profile напрямую. Фреймворк и Vercel должны знать, как обрабатывать маршрут. Используйте официальную конфигурацию, а не универсальный rewrite без понимания последствий.

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

После deploy пользователь может видеть старую версию из браузерного, CDN- или application-кэша. Определите, какие ответы можно кэшировать и на сколько. Персональные данные и ответы с авторизацией не должны случайно стать общими.

Если контент обновляется из CMS, проверьте способ инвалидировать или перестроить страницу. Не ставьте нулевой кэш всему сайту из-за одной динамической секции. Но и не обещайте мгновенное обновление, если build запускается по расписанию.

При диагностике смотрите заголовки ответа и точный deployment URL. Так можно отличить старый production alias от новой preview-версии.

Если в одном репозитории находятся сайт и backend, укажите root directory конкретного приложения. Настройте команды и переменные для него, а не для корня наугад. Проверьте, какие изменения должны запускать новую сборку.

Не копируйте общий .env во все проекты. Каждому deployment нужны только его секреты. Если несколько приложений используют один пакет, тестируйте изменение пакета на всех зависимых проектах до merge.

Проверьте оба варианта домена, www и без него, сертификат, HTTP-to-HTTPS redirect и несколько вложенных страниц. Затем проверьте почтовые DNS-записи: редактирование зоны не должно случайно удалить MX, SPF или DKIM.

Если домен обслуживает старый сайт, уменьшите TTL заранее и подготовьте план возврата. Сохраните предыдущие записи до переключения. После изменения не ориентируйтесь только на свой компьютер: проверьте DNS у нескольких публичных резолверов.

Сделайте контрольный коммит или tag, запишите production URL и версию. Убедитесь, что следующий разработчик понимает путь от ветки до preview и production. Удалите тестовые домены и секреты, которые больше не нужны.

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

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

Собрать проект, довести его до GitHub и пройти контролируемую публикацию можно на курсе «Вайб-кодинг: быстрый старт». Vercel ускоряет deploy, но проверку среды и поведения все равно выполняет команда.

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