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

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

Переменные окружения содержат конфигурацию и секреты, которые приложению нужны на этапе сборки и во время выполнения, например ключи API, URL баз данных и флаги функций, без необходимости хранить все это в репозитории. В этом руководстве рассказывается, где они находятся в Orbit, как работают область действия и приоритет, как отмечать значение как секретное, выполнять массовый импорт и экспорт, а также описываются ошибки, которые приводят к переменной, которая почему-то всегда не определена.

Где они находятся

Откройте проект в Orbit и щелкните вкладку Env vars в /orbit/<project-id>/env-vars.

На странице организованы следующие разделы:

All environments (вверху): переменные уровня проекта, доступные при каждой сборке.
Свертываемый раздел для каждого окружения (Production, Staging и любые preview-версии) с переопределениями для этого окружения.

Над списком находится поле поиска и фильтр Secrets only, которые позволяют быстро ориентироваться в длинном списке.

Как работает область действия

Область действия	Что это влияет
All environments (уровень проекта)	Инжектируется при каждой сборке этого проекта
Environment-level override	Применяется только к этому окружению и имеет приоритет над значением уровня проекта с тем же ключом

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

Типичная конфигурация: переменная уровня проекта DATABASE_URL, указывающая на тестовую базу данных, с переопределением на уровне production, указывающим на реальную. Сборки production получают реальную базу данных, все остальное получает тестовую, и учетные данные production не случайно попадут в preview при добавлении чего-либо позже.

Также есть элемент управления Available in для переменных уровня проекта, который позволяет исключить определенные типы окружений (production, staging, preview) из переменной, которая в остальном является проектной. Полная информация о настройке переменных окружения по окружениям, включая рассуждения безопасности, находится в Установка переменных окружения по окружению.

Переменная уровня проекта инжектируется в сборки branch preview, а URL preview доступны всем, кто знает ссылку. Учетные данные production базы данных, реальные ключи платежей и токены администратора должны быть ограничены только production. Это самое важное, что нужно правильно сделать на этой странице.

Добавление переменной

Прокрутите до формы Add variable в нижней части вкладки Env vars.
Введите KEY, например NEXT_PUBLIC_API_URL.
Введите value.
Выберите Scope: All environments (project-wide) или переопределение для конкретного окружения.
Если вы выбрали project-wide, используйте кнопки Available in, чтобы отменить выделение любых типов окружений, в которые эта переменная не должна попадать.
Установите флажок Mark as secret для всего чувствительного.
Нажмите Add.

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

Когда вступают в силу изменения

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

Orbit явно это показывает. Откройте страницу деталей развертывания и, если конфигурация изменилась с момента его сборки, вы получите уведомление Environment variables updated since this deployment, которое сообщает, что изменение не вступит в силу, пока вы не перестроите проект.

Секреты

Установите флажок Mark as secret для всего, что вы не будете вставлять в чат: ключи API, пароли баз данных, токены, ключи подписи.

Значения секретов замаскированы в панели и имеют значок secret. Несекретные значения показывают маркер (plain).

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

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

Редактирование и удаление

Щелкните значок редактирования рядом с переменной, чтобы изменить ее значение. Нажмите Delete, чтобы удалить его, и подтвердите: диалог предупреждает, что сборки, зависящие от него, сломаются, что является точным описанием того, что произойдет при следующем развертывании.

Массовый импорт и экспорт

Две кнопки в верхней части вкладки обрабатывают массовые операции.

Import .env открывает окно вставки. Вставьте содержимое файла .env, выберите область действия, и Orbit сообщит вам, сколько переменных он обнаружил и сколько он отметит как секретные. Он автоматически отмечает ключи на основе их имен, поэтому все, что содержит SECRET, TOKEN, KEY, PASSWORD и подобное, помечается как секретное перед импортом. Существует опция Overwrite existing variables with the same key, которая по умолчанию отключена.

Download .env создает шаблон, содержащий только имена переменных, без значений. Он предназначен для совместного использования с коллегой, который затем заполняет свои собственные значения, а не использования в качестве резервной копии.

Загрузка шаблона .env никогда не включает значения, включая несекретные переменные. Нет способа экспортировать значения из Orbit. Если вам нужна копия значения, возьмите его из того места, где вы его первоначально создали.

Копирование переменных между окружениями

Панель Copy variables between environments копирует весь набор из одной области действия в другую. Выберите From (уровень проекта или конкретное окружение) и To, при желании установите флажок Overwrite variables that already exist in the target и нажмите Preview, чтобы увидеть точно, сколько будет добавлено, обновлено и пропущено, перед тем как вы подтвердите.

Также существует страница Env sync check, которая сравнивает production и staging ключ за ключом и сообщает, что находится только в одном, что отличается и что совпадает. Это правильный инструмент для вопроса "почему staging работает, а production нет".

Совместное использование переменных между проектами

Если несколько проектов нуждаются в одном учетном данные, используйте env group вместо копирования его в каждый проект. Перейдите в Orbit, затем Env groups, создайте группу, добавьте переменные в нее и свяжите проекты, которые их нуждаются.

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

Примечания к фреймворку

Какие переменные попадают в браузер, решает ваш фреймворк, а не Orbit. Orbit инжектирует все в область действия; фреймворк решает, что раскрыть.

Next.js: ключи с префиксом NEXT_PUBLIC_ встроены в пакет браузера во время сборки. Все остальное остается на стороне сервера.
Vite: ключи с префиксом VITE_ открыты для браузера. Все остальное только для сборки.
Node.js apps: все в области действия находится в process.env во время сборки и во время выполнения, когда Server mode включен.

Никогда не отмечайте значение как секретное, а затем также не используйте префикс NEXT_PUBLIC_ или VITE_. Флаг secret только контролирует, показывает ли панель вам значение; префикс контролирует, отправляет ли ваш фреймворк его в браузер каждого посетителя. Префикс имеет приоритет.

Проверка того, что именно получила сборка

На каждой странице деталей развертывания перечислены ключи переменных окружения, которые были инжектированы во время сборки, и сравниваются их с вашей текущей конфигурацией: добавленные, измененные, удаленные и неизменные. Голубые ключи поступили из переопределения уровня окружения, серые из уровня проекта. Значения никогда не сохраняются и не показываются, но наведение на ключ дает отпечаток SHA-256, который достаточен для подтверждения того, что два окружения содержат одно и то же значение, без его раскрытия.

Это окончательный ответ на вопрос "переменная действительно достигает сборки". Проверьте это перед тем, как что-либо еще изменить.

Устранение неполадок

The variable is undefined at runtime. Проверьте, что развертывание сделано после изменения, затем проверьте, что область действия охватывает это окружение, затем проверьте правила префикса фреймворка выше. В таком порядке.

It works in production but not in a preview. Переменная ограничена только production, или переменная уровня проекта имеет preview не выбранное под Available in. Обычно это намеренно.

It works locally but not in the build. Ваш локальный файл .env находится не в репозитории и не должен там находиться. Импортируйте его с помощью Import .env и выберите правильную область действия.

Staging is missing everything production has. Включите Inherit production env vars в Settings, в разделе Staging: environment variables, или используйте Copy variables between environments.