Переменные окружения лендинга: передача без секретов
Как передать настройки AI-лендинга следующему исполнителю: имена переменных, окружения, время чтения и безопасная проверка подключения.
Следующему исполнителю нужен перечень необходимых настроек и способ проверить их действие. Файл с секретами в чате создаёт риск и всё равно плохо объясняет, какая переменная отвечает за форму, аналитику или генерацию текста.
Я бы включал карту окружения в передачу лендинга, собранного AI-агентом. Она отвечает на операционный вопрос: можно ли запустить нужную версию в нужной среде, не угадывая смысл переменных. Исходники и красивый README без этой карты часто оставляют интеграции в подвешенном состоянии.
Описывайте назначение, а не значение
Сначала найдите места чтения настроек в коде. Для каждой переменной запишите, что она включает, где хранится и что произойдёт без неё. Секретное значение не нужно для этой работы. Фраза «лежит у прошлого разработчика» не подходит как место хранения: укажите систему и роль, которой доступно управление.
| Имя | Назначение | Где читается | Проверка |
|---|---|---|---|
| CONTACT_API_TOKEN | Доступ сервера к получателю заявок | Сервер; уточнить запуск или запрос | Разрешённая тестовая запись дошла получателю |
| NEXT_PUBLIC_SITE_URL | Публичный адрес сайта | Браузерный код при сборке, если используется там | В опубликованной версии правильные ссылки |
| ANALYTICS_ENABLED | Управляет загрузкой измерения | По фактическому месту в приложении | Проверены состояние и запрос загрузчика |
| CONTENT_PREVIEW_TOKEN | Доступ к редакторскому превью | Только сервер | Без доступа превью закрыто; с доступом видно нужный материал |
Добавьте к таблице владельца настройки, допустимое отсутствие, окружения и процедуру обновления. Это рабочая документация конкретного приложения: названия выше нельзя копировать как обязательный стандарт для любого сайта.
Разделите сборку и запуск
В Next.js переменные с префиксом NEXT_PUBLIC_ могут попасть в браузерный JavaScript при сборке. После выпуска эти значения зафиксированы в готовом коде. Это поведение описано в официальной документации Next.js. Переименование секретного токена с таким префиксом не делает его безопасным для публикации.
У серверной переменной тоже надо проверить момент чтения. Код может использовать её при сборке статической страницы, старте процесса или обработке запроса. Общая пометка «server» этого различия не объясняет. Уточните у разработчика фактическую точку использования и требуемое действие после изменения: новая сборка, перезапуск либо следующий запрос.
Например, изменили публичный адрес в панели, перезапустили сервер, а браузер продолжает отправлять форму на старый домен. Причина может быть в уже собранном клиентском коде. Карту таких различий продолжает разбор локальной и опубликованной версии. Проверяйте готовый выпуск, а не только значение в панели.
Что положить рядом с исходниками
- Пример файла настроек с пустыми значениями либо безопасными заглушками и пояснениями.
- Перечень окружений: локальное, тестовое, рабочее, с их назначением и адресами.
- Инструкцию получения штатного доступа к хранилищу секретов.
- Команды запуска и сборки, требования к версии среды и зависимости.
- Признаки успешной проверки каждого внешнего подключения.
Не используйте рабочий токен даже в примерном файле. Не добавляйте полные дампы окружения к отчёту об ошибке. Если нужно подтвердить наличие настройки, достаточно статуса «задана» и результата проверки доступа. Маскированная строка тоже не объясняет, к какому проекту или получателю привязано подключение.
Приёмка передачи: запуск без подсказок автора
Попросите следующего исполнителя развернуть проект в согласованной тестовой среде по документу. Он должен сам определить, каких доступов не хватает, какие значения публичные и чем проверить форму. Список возникающих вопросов покажет пробелы лучше, чем оценка полноты README по длине.
Успешная сборка подтверждает только доступность нужных ей настроек. Для доставки заявки требуется отдельная разрешённая проверка у получателя. Для аналитики — проверка загрузки и нужного события. Для закрытого превью — проверка с доступом и без него. Не объединяйте эти результаты в одну зелёную строку.
Перед рабочим изменением сохраните предыдущую версию настройки в штатном защищённом хранилище и определите действие восстановления. Если обновление требует пересборки, возврат одного значения не вернёт прошлый браузерный пакет. Поэтому карту окружения стоит читать вместе с планом отката лендинга. Полезная передача заканчивается воспроизводимым запуском и понятным восстановлением.