Что такое переменные окружения — и почему ключ нельзя писать прямо в коде

Смотри, на этом обжигаются почти все новички. Ты подключаешь какой-нибудь сервис, он даёт тебе ключ — длинную строку, — ты вставляешь её прямо в код, заливаешь проект на GitHub. И через несколько минут боты, которые круглосуточно сканируют чужие репозитории, находят твой ключ и начинают тратить твои деньги. Звучит страшно — но защита простая и называется «переменные окружения».

Что это такое

Переменная окружения — это значение, которое лежит рядом с приложением, но не внутри кода. Код говорит «дай мне ключ из окружения», а само значение хранится отдельно — там, куда чужие не заглянут.

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

Как это работает

На твоём компьютере секреты обычно складывают в файл с именем .env (от environment, «окружение»). Внутри — простые строки имя = значение:

OPENAI_API_KEY=sk-вот-этот-длинный-секрет
DATABASE_URL=postgres://...

Дальше две важные вещи:

• Код берёт значение по имени, а не хранит его. В коде ты пишешь что-то вроде process.env.OPENAI_API_KEY — это «достань ключ из окружения». Сам секрет в коде не появляется.
• Файл .env не попадает в репозиторий. Ты добавляешь его имя в .gitignore, и Git его игнорирует — он остаётся только у тебя на машине. Поэтому даже публичный код не выдаёт твои ключи.

Когда ты деплоишь приложение, у хостинга есть своё место для этих же переменных — окошко «Environment Variables». Ты вписываешь туда те же ключи, и на сервере код находит их так же по имени.

Почему это важно тебе

Кроме безопасности, тут есть второй смысл — гибкость. У тебя обычно две среды: твой компьютер (разработка) и сервер (продакшн). Часто им нужны разные значения: тестовая база на компе, боевая — на сервере. Если бы адрес базы был вписан в код, тебе пришлось бы менять код при каждом переезде. С переменными окружения код один и тот же, а значения подставляются под среду. Меняешь окружение — не трогаешь код.

И когда ИИ-агент генерирует тебе проект, он почти всегда сам раскладывает секреты по .env и подставляет process.env.* в код. Понимая, что это и зачем, ты не растеряешься, увидев пустой .env.example, и сразу поймёшь: надо вписать свои ключи сюда, а не в код.

Где ты встретишь их первой

Обычно — когда подключаешь первый внешний сервис: API, базу данных, оплату. Тебе дадут ключ и скажут «положи в переменные окружения». Часто рядом с проектом лежит файл .env.example — это шаблон с именами без значений. Скопируй его в .env, впиши свои ключи — и проверь, что .env в .gitignore. Эта одна привычка спасает от самой частой и самой дорогой ошибки новичка.

Вопрос: чем .env отличается от .env.example?

.env — твой настоящий файл с секретами, он не коммитится. .env.example — пустой шаблон, который коммитится специально: в нём перечислены имена нужных переменных, но без значений. По нему любой, кто скачал проект, поймёт, какие ключи завести у себя.

Вопрос: я уже залил ключ в GitHub — что делать?

Сразу считай его скомпрометированным. Удалить из истории Git мало — копия уже могла утечь. Правильно — зайти в сервис, который выдал ключ, и отозвать его (revoke), а затем выпустить новый и положить уже в .env. Чистка истории — потом; первым делом отзови старый ключ.