Управление секретами и переменными окружения

В приложении React переменные окружения делятся на два класса: серверные (никогда не отправляются в браузер) и клиентские (встраиваются в пакет JavaScript). Понимание того, к какому классу относятся ваши переменные, — первый шаг в управлении секретами, поскольку клиентские переменные фактически становятся общедоступными после развертывания пакета.

В проектах Vite в клиентскую сборку включаются только переменные с префиксом VITE_. VITE_PUBLIC_API_URL=https://api.example.com доступна в коде браузера через import.meta.env.VITE_PUBLIC_API_URL. Все остальные переменные удаляются из сборки во время сборки и остаются только на сервере.

В Next.js префикс NEXT_PUBLIC_ делает переменную доступной для JavaScript в браузере. NEXT_PUBLIC_ANALYTICS_ID=UA-123 встраивается в клиентскую сборку. Переменные без этого префикса (например, DATABASE_URL) доступны только в серверном коде (серверных компонентах, маршрутах API и серверных действиях) и никогда не отправляются в браузер.

Переменная без префикса всё равно может стать доступной, если ее случайно сериализовать. Например, если серверный компонент передает клиентскому компоненту весь объект конфигурации в качестве свойства и эта конфигурация включает DATABASE_URL, секрет окажется в HTML, отправленном в браузер. Тщательная передача параметров через компоненты и аудит сериализации предотвращают это.

В клиентской сборке никогда не должны появляться: строки подключения к базам данных и пароли, секретные ключи сторонних API (секретный ключ Stripe, ключ API OpenAI), закрытые ключи RSA/EC, секреты подписи JWT и внутренние токены аутентификации служб. Если для вызова API требуется что-либо из этого, проксируйте вызов через серверную конечную точку.

Шаблон серверной части для интерфейса (BFF) размещает тонкий серверный слой между приложением React и конфиденциальными внешними службами. Клиент вызывает /api/stripe/charge, сервер BFF добавляет секретный ключ Stripe и вызывает API Stripe, а BFF возвращает только необходимые данные ответа. Секреты навсегда остаются на сервере.

dotenv-vault шифрует ваш файл .env и позволяет безопасно делиться им и развертывать его в разных окружениях, не добавляя секреты в открытом виде в систему контроля версий. К производственным альтернативам относятся HashiCorp Vault (корпоративное решение), AWS Parameter Store (SSM) и GCP Secret Manager — все они получают секреты через API во время выполнения, а не во время сборки.

Платформы CI/CD (GitHub Actions, GitLab CI) предоставляют зашифрованное хранилище секретов, доступное в виде переменных окружения во время сборки. Храните секреты в GitHub Secrets и ссылайтесь на них в рабочих процессах как на ${{ secrets.STRIPE_SECRET_KEY }}. Секреты скрываются в журналах и никогда не включаются в собранный артефакт.

Next.js и Vite поддерживают несколько файлов .env: .env (все окружения), .env.local (локальные переопределения, игнорируется системой контроля версий), .env.development, .env.production. Локальный файл переопределяет значения из общего файла, позволяя настраивать приложение для конкретного разработчика, не затрагивая другие окружения.

После сборки проверьте пакет JavaScript на наличие случайно раскрытых секретов. Выполните grep -r "password|secret|api_key" dist/ или используйте специальный инструмент, например анализ strings для собранных файлов. Некоторые секреты при случайном включении легко распознать по формату (UUID, строки base64 или префиксы ключей, такие как sk_live_).

Каждое окружение и каждая служба должны иметь доступ только к необходимым им секретам. Клиенту React вообще не нужны секреты — он должен получать только общедоступные идентификаторы. Серверу BFF нужны лишь секреты, необходимые для вызываемых им API. В окружениях разработки следует использовать ключи API, не относящиеся к производственной среде, с ограниченными разрешениями и лимитами расходов.

Vite использует VITE_, а Next.js — NEXT_PUBLIC_, чтобы передавать переменные в пакет браузера. Все остальные переменные доступны только на сервере. Никогда не включайте пароли баз данных, секретные ключи API или секреты подписи JWT в клиентский код. Используйте шаблон BFF для проксирования конфиденциальных вызовов API. Для управления секретами в рабочей среде используйте dotenv-vault, AWS Parameter Store или GitHub Secrets. Проверяйте собранные пакеты на наличие случайно раскрытых секретов.