Переменные окружения Vercel без файла .env в Git

Эти шаги предназначены для приложения, уже размещённого на Vercel. Понадобится доступ к параметрам проекта и список переменных, которые использует приложение. Пример с NEXT_PUBLIC_ относится именно к Next.js; не переноси эти имена на другие фреймворки без проверки. Инструкция опирается на официальную документацию Vercel и Next.js, но не проверялась в реальном аккаунте.

Практические материалы о Ailoot доступны в документации.

Почему .env не следует отправлять в Git#

Переменная окружения — это настройка, состоящая из имени и значения, которую приложение получает отдельно от исходного кода. Например, программа может искать ключ стороннего сервиса по имени SERVICE_API_KEY. Само значение ключа не следует вставлять в эту инструкцию, переписку с агентом или репозиторий.

Next.js может загружать переменные из локальных файлов .env*, однако файл на компьютере и настройки проекта в Vercel — разные источники конфигурации. Если файл не передан вместе с репозиторием, добавь нужные значения непосредственно на хостинге. Шаблон create-next-app по умолчанию включает .env-файлы в .gitignore; в документации Next.js указано, что обычно их не следует помещать в репозиторий.

Если ещё не ясно, какие данные допустимо хранить в исходниках, начни с проверки безопасности проекта, созданного с помощью ИИ. Здесь рассматривается более конкретный вопрос: где задать конфигурацию для развёртывания на Vercel.

Выясни, где приложение использует переменную#

Перед тем как вводить значения, подготовь перечень имён переменных — без секретных данных. Для каждого имени установи три обстоятельства: для какого окружения оно предназначено, где исполняется обращающийся к нему код и на каком этапе значение требуется.

Окружение Development используют для локальной разработки, Preview — для предварительных развёртываний, а Production — для основной опубликованной версии. Для Preview можно задать отдельные значения для Git-ветки; при совпадении имён веточное значение имеет приоритет над общим значением Preview.

В приложении Next.js переменные без NEXT_PUBLIC_ по умолчанию доступны на серверной стороне. Этот префикс позволяет включить значение в JavaScript, отправляемый браузеру. Он уместен для заведомо публичных данных, например несекретной метки версии, но не для закрытого API-ключа. Даже если префикс не используется, приложение не должно вручную передавать секрет клиентскому коду.

Если фреймворк пока неизвестен, попроси агента определить его по файлам проекта. В сравнении Astro и Next.js описаны различия между ними; правило NEXT_PUBLIC_ нельзя автоматически применять ко всем приложениям React.

Конфигурация хостинга — одна из задач при создании приложения с ИИ-агентом.

Добавь переменную в проект Vercel#

Войди в официальный кабинет и выполни настройку самостоятельно. Не сообщай агенту настоящий ключ для заполнения формы и не отправляй снимки экрана, на которых видно его значение.

1. Открой панель Vercel и выбери нужный проект. Убедись, что это именно то приложение, которое планируешь открыть: одного совпадения с названием репозитория недостаточно.
2. В меню настроек проекта перейди к пункту Environment Variables.
3. Введи в поле Name имя, которое ожидает приложение, например SERVICE_API_KEY. Это лишь образец: если код обращается к переменной с другим именем, укажи его без изменений.
4. В поле Value вставь значение из своего хранилища учётных данных. Не записывай его в исходный код, чат или журнал проверки.
5. Отметь подходящее окружение. Для предварительной версии выбери Preview, для основной опубликованной версии — Production. Не включай один секрет во все окружения без необходимости.
6. Для настройки Preview отдельной ветки проверь, какая ветка выбрана и нет ли для неё собственного значения с тем же именем.
7. Нажми Save.

Vercel предоставляет проектные переменные на этапе сборки и при исполнении серверных функций Vercel Functions. Однако то, что значение доступно среде Vercel, ещё не делает его безопасным для браузера: это зависит от кода приложения и правил фреймворка.

Зачем выпускать новое развёртывание после сохранения#

Сохранённая переменная не меняет уже выпущенные версии приложения. Согласно документации 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, который возвращает содержимое переменной. Сначала проверь на сервере только наличие настройки — «задана» или «отсутствует», — а затем отдельно проверь функцию приложения, использующую сервис. Сам факт наличия переменной не подтверждает ни действительность ключа, ни достаточность его прав.

Зафиксируй итоги без секретных значений:

• выбранные проект, окружение и ветка соответствуют параметрам настройки;
• проверяется URL нового развёртывания, созданного после сохранения переменной;
• сборка завершилась, а нужная функция приложения выполнилась с безопасными тестовыми данными;
• секрет не попал в браузер, ответы API, журналы или переписку.

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

Что делать, если значение равно undefined#

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

Даже если имя и окружение верны и создана новая версия, ошибка функции не обязательно связана с переменной. Изучи конкретную ошибку серверного кода и не публикуй диагностические сведения, содержащие секреты. Эта инструкция не гарантирует устранение любого ответа HTTP 500.

Для переноса приложения на собственный сервер нужны другие шаги — они описаны в руководстве по размещению проекта через Coolify. Названия настроек и порядок действий для Vercel там неприменимы.

Перейти на сайт Ailoot.