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

> Как настроить переменные окружения Vercel для Production и Preview, когда файл .env не хранится в Git, и почему после изменений нужно новое развёртывание. Пример для Next.js с безопасной проверкой без раскрытия секретного ключа.

Source: https://ailoot.ai/blog/ru/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/ru/vercel-environment-variables/
Language: ru
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-c3b9a323c8155ebcea79eb65b1fdc65d5d66b066f9d3d2cce4ca50870b44a5dd


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Если секреты из файла `.env` не добавлялись в Git, внеси необходимые переменные в разделе **Environment Variables** проекта Vercel. Укажи нужное окружение и сохрани настройки, затем выпусти новое развёртывание: существующие версии не обновятся автоматически. В проекте Next.js не присваивай секрету имя с префиксом `NEXT_PUBLIC_`, иначе значение будет включено в клиентский JavaScript при сборке.

</div>

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

[Практические материалы о Ailoot доступны в документации](https://ailoot.ai/docs/).

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

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

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

Если ещё не ясно, какие данные допустимо хранить в исходниках, начни с [проверки безопасности проекта, созданного с помощью ИИ](https://ailoot.ai/blog/ru/vibe-coding-security/). Здесь рассматривается более конкретный вопрос: где задать конфигурацию для развёртывания на Vercel.

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

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

| Что выяснить | Возможные варианты | Для чего это важно |
|----|----|----|
| Окружение Vercel | Development, Preview, Production | Настройка должна соответствовать версии приложения, которую проверяешь |
| Где используется значение | На сервере или в браузере | Приватный ключ нельзя включать в код клиента |
| Когда нужно значение | Во время сборки или исполнения серверной функции | В Next.js публичное значение фиксируется при сборке |

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

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

Если фреймворк пока неизвестен, попроси агента определить его по файлам проекта. В [сравнении Astro и Next.js](https://ailoot.ai/blog/ru/astro-vs-nextjs-for-ai-built-sites/) описаны различия между ними; правило `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` означает, что в проверяемом месте приложение не получило значение переменной. Сверяй сначала её имя, затем окружение и версию; не меняй несколько настроек за один раз.

| Наблюдаемая ситуация | Что следует проверить |
|----|----|
| Локально всё работает, а в Preview — нет | Задано ли это имя в настройках проекта для Preview и соответствует ли выбранная ветка нужной |
| Preview работает, но Production — нет | Добавлено ли имя для Production и выпущена ли новая основная версия после Save |
| В разных Preview-ветках результат отличается | Не переопределено ли общее значение Preview отдельной настройкой ветки с тем же именем |
| Сервер получает переменную, а браузер — нет | Для закрытой переменной Next.js это ожидаемо; не переноси приватный ключ в браузер |
| Публичная метка Next.js не обновилась | Создана ли новая сборка с нужным значением и открыт ли URL именно этого развёртывания |
| Имя публичной переменной верное, но подстановка не срабатывает | Не используется ли динамическое обращение `process.env[varName]`: Next.js не встраивает такие чтения |

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

Для переноса приложения на собственный сервер нужны другие шаги — они описаны в [руководстве по размещению проекта через Coolify](https://ailoot.ai/blog/ru/coolify-claude-code-deploy/). Названия настроек и порядок действий для Vercel там неприменимы.

<div class="section" role="doc-bibliography" aria-label="Список источников">

### Официальные источники

- [Переменные окружения Vercel](https://vercel.com/docs/environment-variables)
- [Добавление переменных и управление ими в Vercel](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Переменные окружения Next.js](https://nextjs.org/docs/app/guides/environment-variables)

</div>

[Перейти на сайт Ailoot](https://ailoot.ai/).

## Вопросы и ответы

### Почему после сохранения в Vercel переменная всё ещё undefined?

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

### Можно ли добавить NEXT_PUBLIC_, чтобы приложение Next.js увидело секрет?

Не используйте этот префикс для секрета: значение попадает в браузерный код при сборке. Храните его на сервере и проверяйте наличие без печати ключа.


## Ailoot · Компания и портфель её проектов

Ailoot опирается на накопленный опыт работы, большую клиентскую базу, стабильный сервис и постоянный контроль KPI.

Компания и портфель её проектов: миллионы клиентов; продажи на миллиарды ежемесячно.

Этот опыт Ailoot использует для API-доступа к нейросетям в продуктах клиентов, агентах, приложениях и автоматизациях.