Инструкция для проекта, который уже размещается на Vercel. Нужны доступ к его настройкам и понимание, какие переменные читает приложение. Пример ниже относится к Next.js; названия переменных другого фреймворка нельзя переносить в него автоматически. Инструкция основана на официальной документации; на реальном аккаунте её не проверяли.
За новыми материалами об ИИ-инструментах можно следить в каналах.
Почему файл .env не нужно добавлять в Git
Переменная окружения - настройка с именем и значением, которую приложение получает отдельно от исходного кода. Например, по имени SERVICE_API_KEY программа обращается к значению ключа внешнего сервиса. Сам ключ в инструкцию, переписку с агентом и репозиторий переносить не нужно.
Next.js умеет загружать переменные из локальных файлов .env*. Но локальный файл и настройки проекта в Vercel - разные места. Если файл не отправлен в репозиторий, задавай значения на хостинге отдельно. Стандартный шаблон create-next-app добавляет .env-файлы в .gitignore; документация Next.js предупреждает, что отправлять их в репозиторий почти никогда не следует.
Если пока непонятно, что можно хранить в исходниках, начни с проверки безопасности проекта, собранного с ИИ. Здесь решаем более узкую задачу: где задать настройки для конкретного развёртывания Vercel.
Сначала выясни, где приложение читает переменную
До ввода значений составь список имён, без самих секретов. Для каждого имени нужно понять три вещи: какое окружение его использует, где выполняется код, который читает переменную, и когда требуется значение.
| Что проверяем | Возможные варианты | Зачем это знать |
|---|---|---|
| Окружение Vercel | Development, Preview, Production | Настройка должна относиться к той версии, которую проверяешь |
| Место чтения | Сервер или браузер | Приватный ключ нельзя включать в клиентский код |
| Момент чтения | Сборка или выполнение серверной функции | В Next.js публичные значения фиксируются при сборке |
Окружение Development предназначено для локальной разработки. Preview - для предварительных развёртываний, а Production - для основной опубликованной версии. У Preview бывают настройки для конкретной Git-ветки: они перекрывают одноимённые общие настройки Preview.
Для проекта Next.js переменные без NEXT_PUBLIC_ по умолчанию доступны на сервере. Префикс NEXT_PUBLIC_ разрешает встраивание значения в JavaScript, который получает браузер. Это подходит для заведомо публичной настройки, например несекретной метки версии, но не для приватного API-ключа. Даже без этого префикса нельзя вручную возвращать секрет клиенту из кода приложения.
Если фреймворк ещё не определён, попроси агента назвать его по файлам проекта. Сравнение Astro и Next.js поможет разобраться в различиях; применять правило NEXT_PUBLIC_ к любому React-приложению нельзя.
Настройки хостинга - одна из задач при работе над приложением с ИИ-агентом. Если нужна более широкая работа с ИИ-агентами, посмотри актуальную программу практикума и соотнеси её со своей задачей. Настройку Vercel в составе программы здесь не обещаем.
Как добавить переменную в проект Vercel
Выполняй действия в официальном кабинете самостоятельно. Не передавай агенту настоящий ключ ради заполнения формы и не прикладывай снимок экрана с его значением.
- Открой панель Vercel и выбери нужный проект. Не ограничивайся совпадением названия репозитория: проверь, что настраиваешь именно приложение, которое собираешься открыть.
- Перейди в Environment Variables в боковом меню настроек проекта.
- В поле Name укажи имя, которое читает приложение, например
SERVICE_API_KEY. Это условное имя; если код ждёт другое, используй его точное написание. - В поле Value введи значение из своего хранилища учётных данных. Не помещай его в исходники, чат или журнал проверки.
- Выбери окружение, которому нужна эта настройка. Для проверки предварительной версии используй Preview; для основной - Production. Не назначай один секрет всем окружениям автоматически.
- Если настройка Preview относится к отдельной ветке, проверь выбранную ветку и возможное одноимённое переопределение.
- Нажми Save.
Vercel предоставляет переменные проекта и во время сборки, и при выполнении серверных функций Vercel Functions. Но доступность значения на стороне Vercel не означает, что его можно отдавать браузеру: это определяется кодом приложения и правилами фреймворка.
Почему после Save нужно новое развёртывание
Сохранение переменной не меняет уже существующие развёртывания. Документация Vercel требует повторно развернуть проект, чтобы новая настройка попала в используемую версию.
При работе через Git новое Production-развёртывание можно создать отправкой коммита в ветку, указанную в настройке Production Branch, а Preview - в другую ветку. Не предполагай, что основной всегда является main: проверь настройку своего проекта. Это должен быть обычный согласованный выпуск проекта, без добавления секретного файла в коммит.
После запуска дождись завершения сборки и открой адрес нового развёртывания. Сохрани для себя его URL, окружение и ветку. Если проверять старый адрес отдельного развёртывания, новые настройки в нём не появятся.
В Next.js есть ещё одно условие: обращения вроде process.env.NEXT_PUBLIC_RELEASE_LABEL заменяются значением во время next build. После сборки это значение зафиксировано. Изменение настройки без новой сборки не перепишет уже выданный клиентский JavaScript.
Как проверить результат, не показывая ключ
Начни с безопасного примера: заведомо несекретной метки NEXT_PUBLIC_RELEASE_LABEL со значением preview-check. Это условные имя и текст, не ключ и не проведённый здесь тест. Если приложение на Next.js читает эту переменную прямым обращением process.env.NEXT_PUBLIC_RELEASE_LABEL, после новой сборки оно может показать метку в предусмотренном для неё месте интерфейса. Такая проверка подтверждает только передачу публичной настройки.
Приватный ключ проверяют иначе. Не выводи его значение, часть, длину или весь process.env. Не создавай публичный адрес, возвращающий содержимое переменной. Для начала проверь на стороне сервера только признак «настройка задана / отсутствует», затем отдельно проверь ту функцию приложения, которая использует сервис. Наличие настройки не доказывает, что ключ действующий или имеет нужные права.
Результаты проверки удобно записать без секретов:
- проект, окружение и ветка совпадают с выбранными при настройке;
- проверяется URL нового развёртывания, выпущенного после сохранения переменной;
- сборка завершилась, а нужная функция приложения отработала на безопасных тестовых данных;
- секрет не выводится в браузер, ответы API, журналы или переписку.
Если функция выполняет платёж, отправку сообщения или другое действие с последствиями, используй предусмотренный сервисом тестовый режим. Проверка настройки сама по себе не даёт разрешения на реальную операцию.
Что проверить, если значение осталось undefined
undefined означает, что в данном месте чтения значение не получено. Иди от имени к окружению и версии, не меняя все настройки одновременно.
| Симптом | Что проверить |
|---|---|
| Локально работает, в Preview нет | Есть ли имя в настройках проекта для Preview; не отличается ли выбранная ветка |
| Preview работает, Production нет | Задано ли имя для Production; создана ли новая основная версия после Save |
| В одной Preview-ветке другое поведение | Нет ли одноимённого значения для этой ветки, перекрывающего общую настройку |
| Сервер видит переменную, браузер нет | Для Next.js это ожидаемо у непубличной переменной; приватный ключ в браузер не переносить |
| Публичная метка Next.js осталась старой | Была ли новая сборка с нужным значением; открыт ли URL именно её развёртывания |
| Публичное имя правильное, но подстановка не работает | Нет ли динамического чтения process.env[varName]: Next.js не встраивает такие обращения |
Если имя, окружение и новая версия проверены, сама ошибка функции ещё не доказывает, что причина в переменной. Проверяй конкретную ошибку серверного кода, не публикуя диагностические данные с секретами. Эта инструкция не обещает устранить любой ответ HTTP 500.
Переезд на собственный сервер требует другого порядка действий: для него есть инструкция по размещению проекта через Coolify. Названия кнопок и порядок настройки Vercel для неё не подходят.
Источники
Новые материалы - дайджестом, без спама
Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.
